Fabric UX React Components

The Fabric UX System represents a leap forward in design consistency and extensibility for Microsoft Fabric. Developed by the Fabric UX Team, this system is a collection of design guidance, common patterns, and reusable components created to empower designers and developers to build consistent, accessible, and engaging workload experiences across Fabric surfaces.

View the Fabric UX System documentation.

The Fabric UX System's React components are built with web components under the hood. This allows all components within the Fabric UX System to share common style, logic, and interaction regardless of the development environment.

Installation

Note: These packages are currently published to the PowerBIClients Azure Artifacts registry, not NPM. You'll need to configure your package manager to use the Azure Artifacts feed.

Registry Information:

• Package: @fabric-msft/fabric-react
• Feed: PowerBIClients at https://dev.azure.com/powerbi/Trident/_artifacts/feed/PowerBIClients

Once you've configured access to the Azure Artifacts feed, you can install the components using:

npm

npm install @fabric-msft/fabric-react

Yarn

yarn add @fabric-msft/fabric-react

After installation, the library is immediately ready for use, allowing developers to begin incorporating Fabric UI components into their React applications with minimal setup.

Configuring and Importing Components

Before diving into the specifics of component usage, it's essential to understand how to configure and import the Fabric React Components library within your project. This step is crucial for ensuring that the components are correctly initialized and ready to be used within your application.

Initial Configuration

Upon successful installation, the next step is to configure your project to use the Fabric React Components. Since these are React components wrapping web components, they integrate seamlessly with standard React applications without additional build configuration.

Importing Components

To use a component, import it into your React project and use it as you would any React component:

import { Badge, Button, LoadingButton } from "@fabric-msft/fabric-react";

const MyComponent = () => (
  <div>
    <Badge shape="rounded" size="large" color="danger">
      New Feature
    </Badge>
    <Button appearance="primary">Click me</Button>
    <LoadingButton loading={true}>Loading</LoadingButton>
  </div>
);

Using Fabric UX React Components

With the components imported, you can start incorporating them into your React applications. Here are some examples:

import {
  Badge,
  Button,
  Dialog,
  Card,
  CardHeader,
  CardPreview,
  Checkbox,
  TextInput,
  Dropdown,
  DropdownOption
} from "@fabric-msft/fabric-react";

function FabricInterface() {
  return (
    <div>
      {/* Basic components */}
      <Badge shape="rounded" size="large" color="danger">
        New Feature
      </Badge>

      <Button appearance="primary">Click me</Button>

      {/* Dialog with slots */}
      <Dialog>
        <div slot="heading">Dialog Title</div>
        <p>Dialog content goes here.</p>
        <div slot="footer">
          <Button appearance="secondary">Cancel</Button>
          <Button appearance="primary">Confirm</Button>
        </div>
      </Dialog>

      {/* Card component */}
      <Card>
        <CardHeader>
          <div slot="header">Card Title</div>
          <div slot="description">Card description</div>
        </CardHeader>
        <CardPreview>Card content area</CardPreview>
      </Card>

      {/* Form components */}
      <Checkbox>Accept terms and conditions</Checkbox>
      <TextInput placeholder="Enter your name" />

      <Dropdown>
        <DropdownOption value="option1">Option 1</DropdownOption>
        <DropdownOption value="option2">Option 2</DropdownOption>
      </Dropdown>
    </div>
  );
}

Setting the Fabric Theme

Out of the box, the components do not include CSS variables. This may make some components feel "unstyled". CSS variables must be applied to your application to see the Fabric UX System's design language.

To apply the Fabric design language, install the theme package and set up the theme:

npm install @fabric-msft/theme

At the root of your React application, add the following snippet to install all the CSS variables:

import { fabricLightTheme, setTheme } from "@fabric-msft/theme";

// Add this to your app's entry point
setTheme(fabricLightTheme);

Listening for Events from Fabric UX System Components

For React-wrapped Fabric UX System components, events can be listened to just like any other native React event, thanks to the wrapper abstracting the complexity of custom events. This means you can use the onEventName pattern (e.g., onClick, onChange) directly in your JSX, providing a callback function to handle the event.

import { Button, Dropdown, Checkbox } from "@fabric-msft/fabric-react";

function MyComponent() {
  const handleButtonClick = (event) => {
    console.log("Button clicked:", event);
  };

  const handleDropdownChange = (event) => {
    console.log("Dropdown value changed:", event.target.value);
  };

  const handleCheckboxChange = (event) => {
    console.log("Checkbox checked:", event.target.checked);
  };

  return (
    <div>
      <Button onClick={handleButtonClick} appearance="primary">
        Click me
      </Button>

      <Dropdown onChange={handleDropdownChange}>
        <DropdownOption value="option1">Option 1</DropdownOption>
        <DropdownOption value="option2">Option 2</DropdownOption>
      </Dropdown>

      <Checkbox onChange={handleCheckboxChange}>Subscribe to updates</Checkbox>
    </div>
  );
}

Styling Fabric UX Components

Web components have some styling differences from typical components in React. In every web component is a shadowDOM that is separate from the html element's view. The shadowDOM is a protected tree that is not directly accessible by standard CSS selectors. Web components provide their own API for accessing and styling the shadowDOM:

CSS Variables

Sometimes the web component will expose CSS variables that can be used to target specific aspects of styling:

fabric-button {
  --button-padding: 12px;
}

fabric-card {
  --card-border-radius: 8px;
}

fabric-badge {
  --badge-font-size: 14px;
}

Slots, Attributes, and Properties

Web components support named and default slots for flexible content placement:

<Dialog>
  <div slot="heading">Dialog Title</div>
  Main dialog content
  <div slot="footer">
    <Button appearance="secondary">Cancel</Button>
    <Button appearance="primary">OK</Button>
  </div>
</Dialog>

<Card>
  <CardHeader>
    <div slot="header">Card Title</div>
    <div slot="description">Card subtitle</div>
  </CardHeader>
  <CardPreview>Card content</CardPreview>
</Card>

Set properties via props:

<Button disabled />
<TextInput readonly />
<Slider min={0} max={100} />

API Parity Notes

Fabric React wrappers are React adapters around Fabric Web Components. Many base controls build on Fluent UI Web Components and follow Fluent design, but exact parity with Fluent UI React isn't guaranteed because the underlying primitives are web components.

What this means for React consumers:

• We aim for design/behavior parity where it makes sense, but some APIs differ by nature of web components.
• Differences you may encounter:
  • Props: names/value shapes may differ from Fluent UI React.
  • Events: custom DOM events vs React synthetic events; wrapper forwards as onX handlers.
  • Composition: slots instead of children-only composition.
  • Styling: CSS variables and ::part selectors instead of className overrides.

VS Code Settings

To get the best experience when using this package in VS Code, we recommend adding the following lines to your .vscode/settings.json file:

{
  "html.customData": [
    "./node_modules/@fabric-msft/fabric-react/dist/fabric-react.html.json"
  ],
  "css.customData": [
    "./node_modules/@fabric-msft/fabric-react/dist/fabric-react.css.json"
  ]
}