@n8d/htwoo-react

HTWOO ReactJS Components

HTWOO ReactJS is an open source alternative for Microsoft's various implementations of their Fluent UI Web Design system. This library consists of flexible ReactJS components based on the HTWOO UI library. For a complete listing please see HTWOO Core Style Guide.

Complete documentation of the HTWOO ReactJS components

How To Use

Note: This component library is currently under development and will most likely continue to make improvements that could likely bring about breaking changes. Please feel free to submit your enhancement ideas and feedback to the issues list so that we can try to address them.

Initialize library in Microsoft SharePoint Framework (SPFx)

1. Install package in your solution.

   This package has a peer dependency on the correspoinding version of @n8d/htwoo-core so that will be added automatically for you.

   npm i @n8d/htwoo-react --save

2. Add a reference to the style.prod.scss file in your solutions root .scss file. Put the reference inside of the webparts base class so that the styles are scoped to the instance of this webpart:

   Note: The import is wrapped in :global so that the class names will not be modified with a namespace.

   .myWebPartRoot{
     :global {
       @import 'node_modules/@n8d/htwoo-core/lib/sass/style.prod';
     }
   }

   then in your root component's top level HTML element add a reference to that base class. This will make sure that when your project builds, the styles will be included. For example:

   public render(): React.ReactElement<IHtwooReactDemoProps> {
     try {
       return (
         <div className={styles.myWebPartRoot}>
           Hello World
         </div>
       );
     } catch (err) {
       console.error(`${this.LOG_SOURCE} (render) - ${err}`);
       return null;
     }
   }
   

3. To initilize the basic SVG icons add the following line to your components main ts file's onInit method:

   import { symset } from '@n8d/htwoo-react/SymbolSet';
   
   public async onInit(): Promise<void> {
     // Initialize Icons Symbol Set
     await symset.initSymbols();
   }

   Alternately you can load your own icon symbol set by passing the path into the initSymbols method:

   This will load both the default hoo-icons as well as whatever icons are in your referenced file.

   import { symset } from '@n8d/htwoo-react/SymbolSet';
   
   public async onInit(): Promise<void> {
     // Initialize Icons Symbol Set with Custom Symbol File
     const symbolSetFile: string = require("./images/icons.svg");
     await symset.initSymbols(symbolSetFile);
   }

   A SVG symbol file will look similar to the following:

   <svg aria-hidden="true" style="position: absolute; width: 0; height: 0; overflow: hidden;" version="1.1"
     xmlns="http://www.w3.org/2000/svg"
     xmlns:xlink="http://www.w3.org/1999/xlink">
     <defs>
         <symbol id="icon-arrow-left" viewBox="0 0 32 32">
             <path d="M22.547 31.953l-15.969-15.953 15.969-15.953 1.406 1.406-14.531 14.547 14.531 14.547-1.406 1.406z"></path>
         </symbol>
     </defs>
   </svg>

   If you are looking to load icons from the @n8d\htwoo-icons library you can install the package and then import them by referencing the svg file in the node_modules folder.

   import { symset } from '@n8d/htwoo-react/SymbolSet';
   
   public async onInit(): Promise<void> {
     // Initialize Icons Symbol Set with HTWOO-Icons
     const fuireg: string = require("@n8d/htwoo-icons/fluent-ui-regular/fluent-ui-regular.svg");
     await symset.initSymbols(fuireg);
   }

   To use the icons in this file, you will reference them by the individual icon's id value, which in the SVG file sample above is icon-arrow-left. Here's an example of using an icon in the HOOAction component

   <HOOAction iconName="hoo-icon-plus" label="Action Button" type={HOOActionType.Action}/>

4. (Optional) Add theme support to your SPFx project

   a. Modify your components manifest and add supportsThemeVariants which allows any of the hTWOo components to render properly in colored SharePoint section.

   { 
     //...
     "supportsThemeVariants": true,
     // ...
   }

   b. Add the following helper code to your components main ts file's onInit method which initializes the CSS Variables to support themes. Make sure to add the import and the private _spfxThemes variable:

   import { ThemeProvider } from '@microsoft/sp-component-base';
   import { SPFxThemes, ISPFxThemes } from '@n8d/htwoo-react/SPFxThemes';
   
   private _spfxThemes: ISPFxThemes = new SPFxThemes();
   
   public async onInit(): Promise<void> {
     // Consume the new ThemeProvider service
     const microsoftTeams = this.context.sdks?.microsoftTeams;
     const themeProvider = this.context.serviceScope.consume(ThemeProvider.serviceKey);
     this._spfxThemes.initThemeHandler(this.domElement, themeProvider, microsoftTeams);
   
     // If no ThemeProvider service, do not include property which will use page context
     this._spfxThemes.initThemeHandler(document.body);
   }

   There are two other alterivatives to adding theme support, for more information please check out the SPFxThemes Class documentation.

5. Import the HTWOO component that you want to use into your own projects components. All components are selectively importable from the /lib/ folder. We will be working on fully documenting all components and their implementation soon.

HTWOO Base Concept

hTWOo style guide, documentation and building platform is based on patternlab.io. To allow the most flexible implementation of designs and design pattern it follows the Atomic Design Methodology coined by Brad Frost around 2012 / 2013.

We're tasked with making interfaces for more users in more contexts using more browsers on more devices with more screen sizes and more capabilities than ever before. That's a daunting task indeed. Thankfully, design systems are here to help. - Brad Frost

Engage

Follow us on Twitter @htwooui.

Maintainer: Stefan Bauer (N8D), Julie Turner

Contributor: You ❤️