Use Fluent UI React in Office Add-ins

Fluent UI React is the official open-source JavaScript front-end framework designed to build experiences that fit seamlessly into a broad range of Microsoft products, including Office. It provides robust, up-to-date, accessible React-based components which are highly customizable using CSS-in-JS.

Note

This article describes the use of Fluent UI React in the context of Office Add-ins. But it is also used in a wide range of Microsoft 365 apps and extensions. For more information, see Fluent UI React and the open source repo Fluent UI Web.

This article describes how to create an add-in that's built with React and uses Fluent UI React components.

Create an add-in project

You'll use the Yeoman generator for Office Add-ins to create an add-in project that uses React.

Install the prerequisites

  • Node.js (the latest LTS version).

  • The latest version of Yeoman and the Yeoman generator for Office Add-ins. To install these tools globally, run the following command via the command prompt.

    npm install -g yo generator-office
    

    Note

    Even if you've previously installed the Yeoman generator, we recommend you update your package to the latest version from npm.

Create the project

Run the following command to create an add-in project using the Yeoman generator.

yo office

Note

When you run the yo office command, you may receive prompts about the data collection policies of Yeoman and the Office Add-in CLI tools. Use the information that's provided to respond to the prompts as you see fit.

When prompted, provide the following information to create your add-in project.

  • Choose a project type: Office Add-in Task Pane project using React framework
  • Choose a script type: TypeScript
  • What do you want to name your add-in? My Office Add-in
  • Which Office client application would you like to support? Word

Screenshot showing the prompts and answers for the Yeoman generator in a command line interface.

After you complete the wizard, the generator creates the project and installs supporting Node components.

Tip

You can ignore the next steps guidance that the Yeoman generator provides after the add-in project's been created. The step-by-step instructions within this article provide all of the guidance you'll need to complete this tutorial.

Try it out

  1. Navigate to the root folder of the project.

    cd "My Office Add-in"
    
  2. Complete the following steps to start the local web server and sideload your add-in.

    Note

    Office Add-ins should use HTTPS, not HTTP, even when you are developing. If you are prompted to install a certificate after you run one of the following commands, accept the prompt to install the certificate that the Yeoman generator provides. You may also have to run your command prompt or terminal as an administrator for the changes to be made.

    Tip

    If you're testing your add-in on Mac, run the following command before proceeding. When you run this command, the local web server starts.

    npm run dev-server
    
    • To test your add-in in Word, run the following command in the root directory of your project. This starts the local web server and opens Word with your add-in loaded.

      npm start
      
    • To test your add-in in Word on a browser, run the following command in the root directory of your project. When you run this command, the local web server starts. Replace "{url}" with the URL of a Word document on your OneDrive or a SharePoint library to which you have permissions.

      npm run start:web -- --document {url}
      

      The following are examples.

      • npm run start:web -- --document https://contoso.sharepoint.com/:t:/g/EZGxP7ksiE5DuxvY638G798BpuhwluxCMfF1WZQj3VYhYQ?e=F4QM1R
      • npm run start:web -- --document https://1drv.ms/x/s!jkcH7spkM4EGgcZUgqthk4IK3NOypVw?e=Z6G1qp
      • npm run start:web -- --document https://contoso-my.sharepoint-df.com/:t:/p/user/EQda453DNTpFnl1bFPhOVR0BwlrzetbXvnaRYii2lDr_oQ?e=RSccmNP

      Note

      If you are developing on a Mac, enclose the {url} in single quotation marks. Do not do this on Windows.

      If your add-in doesn't sideload in the document, manually sideload it by following the instructions in Manually sideload add-ins to Office on the web.

  3. To open the add-in task pane, on the Home tab, choose the Show Taskpane button. Notice the default text and the Run button at the bottom of the task pane. In the remainder of this walkthrough, you'll redefine this text and button by creating a React component that uses UX components from Fluent UI React.

    Screenshot showing the Word application with the Show Taskpane ribbon button highlighted and the Run button and immediately preceding text highlighted in the task pane.

Create a React component that uses Fluent UI React

At this point, you've created a very basic task pane add-in that's built using React. Next, complete the following steps to create a new React component (ButtonPrimaryExample) within the add-in project. The component uses the Label and PrimaryButton components from Fluent UI React.

  1. Open the project folder created by the Yeoman generator, and go to src\taskpane\components.
  2. In that folder, create a new file named Button.tsx.
  3. In Button.tsx, add the following code to define the ButtonPrimaryExample component.
import * as React from 'react';
import { PrimaryButton, IButtonProps } from '@fluentui/react/lib/Button';
import { Label } from '@fluentui/react/lib/Label';

export class ButtonPrimaryExample extends React.Component<IButtonProps, {}> {
  public constructor(props) {
    super(props);
  }

  insertText = async () => {
    // In the click event, write text to the document.
    await Word.run(async (context) => {
      let body = context.document.body;
      body.insertParagraph('Hello Fluent UI React!', Word.InsertLocation.end);
      await context.sync();
    });
  }

  public render() {
    let { disabled } = this.props;
    return (
      <div className='ms-BasicButtonsExample'>
        <Label>Click the button to insert text.</Label>
        <PrimaryButton
          data-automation-id='test'
          disabled={ disabled }
          text='Insert text...'
          onClick={ this.insertText } />
      </div>
    );
  }
}

This code does the following:

  • References the React library using import * as React from 'react';.
  • References the Fluent UI React components (PrimaryButton, IButtonProps, Label) that are used to create ButtonPrimaryExample.
  • Declares the new ButtonPrimaryExample component using export class ButtonPrimaryExample extends React.Component.
  • Declares the insertText function that will handle the button's onClick event.
  • Defines the UI of the React component in the render function. The HTML markup uses the Label and PrimaryButton components from Fluent UI React and specifies that when the onClick event fires, the insertText function will run.

Add the React component to your add-in

Add the ButtonPrimaryExample component to your add-in by opening src\components\App.tsx and completing the following steps.

  1. Add the following import statement to reference ButtonPrimaryExample from Button.tsx.

    import {ButtonPrimaryExample} from './Button';
    
  2. Remove the following import statement.

    import Progress from './Progress';
    
  3. Replace the default render() function with the following code that uses ButtonPrimaryExample.

    render() {
      return (
        <div className="ms-welcome">
        <Header logo="assets/logo-filled.png" title={this.props.title} message="Welcome" />
        <HeroList message="Discover what this add-in can do for you today!" items={this.state.listItems} >
          <ButtonPrimaryExample />
        </HeroList>
        </div>
      );
    }
    
  4. Save the changes you've made to App.tsx.

See the result

In Word, the add-in task pane automatically updates when you save changes to App.tsx. The default text and button at the bottom of the task pane now shows the UI that's defined by the ButtonPrimaryExample component. Choose the Insert text... button to insert text into the document.

Screenshot showing the Word application with the "Insert text..." button and immediately preceding text highlighted.

Congratulations, you've successfully created a task pane add-in using React and Fluent UI React!

See also