# Fabric Web 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](https://aka.ms/fabricux).

Fabric Web Components is a library that composes @microsoft/fast-foundation and supports Microsoft's Fluent design language.

## 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-web](https://dev.azure.com/powerbi/Trident/_artifacts/feed/PowerBIClients/Npm/@fabric-msft%2Ffabric-web/overview/)
- **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**

```bash
npm install @fabric-msft/fabric-web
```

**Yarn**

```bash
yarn add @fabric-msft/fabric-web
```

After installation, the library is immediately ready for use, allowing developers to begin incorporating Fabric UI components into their web 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 Web 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 Web Components. This involves setting up your build toolchain to recognize and correctly process the custom elements and associated styles provided by the library. Depending on your project setup, this might require additional plugins or configuration tweaks to support web components fully.

For detailed configuration instructions, [refer to this guide from MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_Components).

### Importing Components

To use a component, import it into your JavaScript or TypeScript file as follows:

```typescript
import {
  Badge,
  BadgeDefinition,
  Button,
  ButtonDefinition
} from "@fabric-msft/fabric-web";

// Define the custom elements
BadgeDefinition.define();
ButtonDefinition.define();
```

## Using Fabric Web Components

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

```html
<fabric-badge shape="rounded" size="large" color="danger">
  New Feature
</fabric-badge>

<fabric-button appearance="primary">Click me</fabric-button>

<fabric-dialog>
  <div slot="heading">Dialog Title</div>
  <p>Dialog content goes here.</p>
  <div slot="footer">
    <fabric-button appearance="secondary">Cancel</fabric-button>
    <fabric-button appearance="primary">Confirm</fabric-button>
  </div>
</fabric-dialog>
```

## Customization and Theming

Fabric Web Components are designed with customization in mind, allowing developers to apply custom themes and styles to align with their application's branding. The library supports theming through CSS custom properties, enabling a flexible approach to styling components.

To apply a theme, you can import and use the theme utilities provided by the [Fabric theme library](https://www.npmjs.com/package/@fabric-msft/theme):

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

// Apply the light theme
setTheme(fabricLightTheme);
```

This code snippet demonstrates how to apply the Fabric light theme to your application, ensuring that the components adhere to a consistent visual style.

## Understanding Custom Events in Web Components

Fabric Web Components use conventional naming for events (click, dismiss, etc). For components that use custom events, use `addEventListener` or inline listeners:

```javascript
document
  .querySelector("fabric-stepper")
  ?.addEventListener("stepschanged", (e) => {
    console.log("Steps changed:", e.detail);
  });

document
  .querySelector("fabric-popover")
  ?.addEventListener("hidePopover", (e) => {
    console.log("Popover hidden:", e.detail);
  });
```

## CSS Variables

Customize component appearance using component-level variables. Some web components expose CSS variables for specific styling aspects:

```css
fabric-filter-pill {
  --icon-spacing: 8px;
}

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

## Slots, Attributes, and Properties

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

```html
<fabric-dialog>
  Dialog content
  <fabric-button slot="action">Close</fabric-button>
</fabric-dialog>
```

Set properties via attributes:

```html
<fabric-slider size="large"></fabric-slider>
<fabric-slider readonly></fabric-slider>
```

## 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:

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