@fluent-blocks/react v9.2.0

Open Storybook ↗︎

Fluent Blocks is a React implementation of Fluent & UI Kit designs for app development based on @fluentui/react-components. This project succeeds @fluentui/react-teams.

This package provides a set of components developers can use to build fully interactive & accessible experiences using whatever React coding convention they prefer, rendering experiences that match Fluent & UI Kit designs.

⚠️ In active development

This project’s API is subject to unannounced breaking changes and is not yet on any release cycle.

Development & contributing

If you’d like to run the development environment or contribute to this project, please see the Contributing file.

Getting started

1. Using TypeScript and an IDE that supports type inspections will make using this project much easier
2. Since this project is not published to NPM yet, do the following:
   1. Clone this repo, cd to packages/react within this repo
   2. Run your package manager’s link command (npm link, yarn link, pnpm link)
   3. cd to your project
   4. Use the same package manager you used earlier to add @fluentui/react-blocks to your project
3. Make sure to resolve any peer dependency warnings; currently all peer dependencies are needed at the right versions for this package to work
4. Use the View component to hand off all UI responsibility to this project, or use individual components as you need, whichever suits your needs best.

How design pattern usage is validated through types

Since the goal of this library is to aid in implementing experiences that conform to Fluent & UI Kit designs and principles, it brings with it those design systems’ opinions. Each component has a concept for what kind of properties & content it accepts, which can be provided in one of two ways:

1. As serializeable props, e.g. {icon: 'fluent', size: 24}
2. As a JSX element, e.g. <Icon icon='fluent' size={24}/>

The bolded terms are used in the TypeScript types for the components in this project, e.g. a valid icon instance matches IconPropsOrElement, which is either 1) IconProps, or 2) IconElement.

For consistency between the two syntaxes, the children prop and its implicit nesting equivalent in JSX is avoided in favor of named content props that parallel the serializeable syntax.

Some top-level components like View will check the props it was provided and provide a detailed error if the props are incorrect in any way. All other components won’t check for issues and will simply refuse to render unexpected content. In either case, developers can explicitly mark where exceptions should be made using the Escape component described below.

Escaping validation

These components won’t render a component that has unexpected props or content, unless you use Escape. If you feel the need to use a pattern not provided by this project, you can do so using the Escape component as a JSX element in any of a component’s content props that aren’t “tightly-bound”, e.g.:

// Only Escape imported from this package will render,
// so make sure you’ve imported it:
import { Section, Escape } from '@fluentui/react-blocks';

<Section
  title={[
    <Escape contentMeetsAccessibilityAndDesignStandards key="t1">
      <strong>You can put anything here</strong>
      <span> and it will be rendered.</span>
    </Escape>,
  ]}
/>

Exceptions: tightly bound components

A component may ignore Escape only if it is “tightly-bound” with another component. Components are tightly-bound when they make sense only when used together, e.g. Layout and LayoutItem where Layout will only render LayoutItems in its items prop. If you need to render special content in such a situation, you can either replace the entire parent with Escape, or use Escape as the content of one of the children.

Escape inclusively, and share your designs!

Make sure the content you add using Escape conforms to WCAG 2.1 and is designed inclusively.

If you would like to share your pattern with the community, we’d welcome your contribution! We’d all thank you to submit PR’s that extend this project with your accessible high-quality patterns.

Concepts

This library harmonizes the patterns in Fluent and the UI Kit with concepts from web layout & interactivity by delivering components organized into these categories:

• General components based on formatting context:
  • Block vs Inline
• Specialized clusters of components with shared interactivity considerations:
  • Media, e.g.:
    • Illustration
    • Chart
  • Inputs, e.g.:
    • RadioGroup
    • ShortTextInput
• Surfaces, each of which expect to be unique in a given view
• Views, the top-level components which render an entire UI in a viewport

Any component may also have Exemplars, which render the same component but with a specialized API surface optimized for a specific use-case for the pattern, e.g. Widget always renders a Card though its props are based on the more constrained scope of content for cards in a dashboard from the UI Kit.

Icons

This project supports using icons from fluentui-system-icons through SVG sprites implemented in an experimental fork of that project. The Icon component will render an SVG of the appropriate size containing a use element with an href to the appropriate sprite, e.g.:

// If used wherever `InlineSequence` or `IconPropsOrElement` is accepted,
// both the props syntax and element syntax will be rendered the same way.
const catIcon =
  { icon: 'animal_cat', size: 24, variant: 'outline' } ||
  <Icon icon='animal_cat' size={24} variant='outline'/>

This project currently expects any requests to /sprites/** to serve an SVG sprite with the appropriate content, which for the Storybook development server is proxied to a specific release on jsDelivr.

In your own project, we recommend serving just the sprites you need locally if possible. Do not use proxies for icons in production.