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

Getting Help/Giving Feedback

Please feel free to submit your questions, enhancement ideas, and feedback to the GitHub issues list so that we can try to address them.

Getting Started with HTWOO-REACT

This documentation will walk you through getting started with this library. In addition you can review the video version of this solution to see a walk through of the process.

To get all the details on what has been released when check out our REACT_CHANGELOG.

Getting Started Walkthrough

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

2. Import htwoo-core styles

Add a @use statement at the top of your solutions root .scss file and then add an @include reference to the htwoo-core.scss file. Put the @include 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.

@use 'sass:meta';

.myWebPartRoot{
  :global {
    @include meta.load-css('node_modules/@n8d/htwoo-core/lib/sass/htwoo-core');
  }
}

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<IMyComponentProps> {
  try {
    return (
      <div className={styles.myWebPartRoot}>
        Hello World
      </div>
    );
  } catch (err) {
    console.error(`${this.LOG_SOURCE} (render) - ${err}`);
    return null;
  }
}

3. Initialze Basic SVG Icons

To initilize the basic SVG icons, used by some of the more complex components, add the following line to your project starting method. In Microsoft SharePoint Framework (SPFx) that would be in the project's main ts file's onInit method.

For more detailed information on using the SymbolSet see the Advanced/SymbolSet Class documentation.

This example shows initializing in an SPFx project.

import { symset } from '@n8d/htwoo-react/SymbolSet';

public async onInit(): Promise<void> {
  // Initialize Icons Symbol Set
  await symset.initSymbols();
}

Add more icons from a custom symbolset file

Alternatively if you have icons in your own symbolset file**, you can add them by passing the path into the initSymbols method: Note: This will load both the basic SVG icons referenced above as well as whatever icons are in your referenced file, so you only need to do one call.

**New in hTWOo is the Icon Tool{:target="_blank"} to create your own symbolset file. This tool allows you to select icons from hoo-icons in regular/filled styles and then download the resulting file to use in your solution.

Add a typing for svg files to be read as a module (images.d.ts):

file: images.d.ts

declare module '*.svg' {
  const content: any;
  export default content;
}

Then import the svg file and pass it to initSymbols method:

This example shows initializing in an SPFx project.

import { symset } from '@n8d/htwoo-react/SymbolSet';
import symbolSetFile from './images/icons.svg';

public async onInit(): Promise<void> {
  // Initialize Icons Symbol Set with Custom Symbol File
  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>

Add more icons from @n8d/htwoo-icons

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.

To register multiple svg files, make additional calls to symset.initSymbols passing in additional svg file references.

First, add a typing for svg files to be read as a module (images.d.ts), then import the svg file and pass it to initSymbols method:

This example shows initializing in an SPFx project.

import { symset } from '@n8d/htwoo-react/SymbolSet';
// Requires typings to be declared in an images.d.ts file
import fuireg from '@n8d/htwoo-icons/fluent-ui-regular/fluent-ui-regular.svg';

public async onInit(): Promise<void> {
  // Initialize Icons Symbol Set with HTWOO-Icons
  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='icon-arrow-left' label='Action Button' type={HOOActionType.Action}/>

4. Add theme support

SPFx projects

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

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

1. 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);
}

For more detailed information on using the SPFxThemes see the Advanced/SPFxThemes Class documentation.

Platform without Microsoft theme support

If you're hosting your solution outside of the Microsoft 365 platform you will need to provide your themes in an alternative manner. The library provides a helper class for applying the theme CSS variables to the root dom element.

First you must define your theme colors. You can do this in a few different ways. The @n8d/htwoo-core library which is a dependency, includes some pre-defined themes. You can import that theme into your project and then pass it to an instance of the GenericThemes class which will then apply that theme to your root DOM element. You can alternatively create your own theme files in json or in code and pass them into the GenericThemes class.

For more information and samples see the Advanced/GenericThemes Class documentation.

5. Start using the components

Import the HTWOO component that you want to use into your own projects components. All components are selectively importable from the root library.

Please see the table of contents on the left side of the page or the Find component function to find the specific components you would like to use and examples of how to use them.

Example of using the HOOLabel atom component

Note the use of rootElementAttributes (Acknowledged that this is NOT a real world use) which is a typed interface for all the HTML Attributes of the root dom element for the component. Use this object as a way to overriding and/or adding additoinal accissibility properties to the element.

import HOOLabel from '@n8d/htwoo-react/HOOLabel';

public render(): React.ReactElement<IMyComponentProps> {
  try {
    const labelREA = {"aria-hidden": true};
    return (
      <div data-component={this.LOG_SOURCE}>
        <HOOLabel label='My Label' rootElementAttributes={labelREA} />
      </div>
    );
  } catch (err) {
    console.error(`${this.LOG_SOURCE} (render) - ${err}`);
    return null;
  }
}

Engage

Follow us on Twitter @htwooui.

Maintainer: Stefan Bauer (N8D), Julie Turner

Contributor: You ❤️