DEV Community: Paul Gildea

Fluent Insights EP4: Slots

Paul Gildea — Tue, 29 Nov 2022 19:10:52 +0000

Fluent UI Insights is a series that describes the design and decisions behind the Fluent UI design system.

In the fourth episode, members of the Fluent UI team explain implementation details and context behind APIs in Fluent UI React v9: slots, JSX children and triggers.

In this video the team covers a ton of history around slots and their evolution to what they are in Fluent UI React.

Timestamps:
00:00 – Bloopers
00:22 – Intention and motivation for slots
01:53 – Slots v1 in Semantic UI React
03:33 – Slots v2 in Stardust UI React
04:42 – Slots v3 in Fluent UI React v9
06:04 – Component groups: collections and elements
06:50 – Collections API in Semantic UI React
07:45 – JSX children to define components
08:11 – Issues with React Context and useContextSelector
09:03 – Limitations of JSX approach
10:43 – Connection between a host component and children
11:33 – Why triggers API is needed?
12:35 – Triggers API journey
13:24 – Triggers API in Fluent UI React v9
14:36 – Limitations of Triggers API
14:56 – Summary of the episode
15:27 – Bloopers

Enjoy!

Check out slots in action with this simple post on how to use them:

Using Slots with Fluent UI React v9

Paul Gildea ・ Jul 8 ・ 5 min read

#fluentui #webdev #tutorial #react

As always let us know what kind of content you want see from Fluent - UI React by visiting us on:

GitHub: https://github.com/microsoft/fluentui
Docs: https://react.fluentui.dev
Twitter: https://twitter.com/fluentui

What's new with Fluent UI React v9: October Update

Paul Gildea — Wed, 19 Oct 2022 15:21:50 +0000

Highlights

First, we recommend folks checkout our latest update on the Component Lifecycle Process and our Component Roadmap as it's been updated for FY23Q2.

Here's what we'll cover in this post:

Added a dedicated shim package for v8 to v9 migration
Released new components in Stable: Dialog 🎉
Added new components in Preview: Table, Field, AvatarGroup, Persona, Toolbar
Check out a Fluent UI React v9 based Teams App demo at Ignite 2022

Migration shims

We know a lot of customers are migrating from Fluent UI React v8 to v9 and we're trying to balance the amount of compatibility shims we build verses building new features in v9.

So we've elevated the Migration section in documentation to cover some of the common migration shims when moving from v8 to v9.

Also we've released those shims in a separate migration package to help you along the way.

To set expectations, at this time we don't intend to shim every component in v8 (as we want customers to adopt v9), but we understand the need to having a compatibility layer for time-sensitive feature development.

Let us know if there are common migration issues you've been hitting so that we help smooth out the experience.

New components in stable

Dialog

This is our latest component to be promoted to stable!

The Dialog provides the fundamental building blocks components needed to create a Dialog experience:

Dialog
DialogTrigger
DialogSurface
DialogTitle
DialogActions

This allows you to easily compose an experience for specific applications to customize the UX.

It also provides a minimum breakpoint to reposition content within the DialogActions.

Give it a try and let us know what you think!

New components in preview

Note: These components are currently under development and are subject to change.

Table

This component has been a long time coming and we're making great progress.

Leveraging the composition-based principles already in the UI library, the Table component is a way for developers to build a "DataGrid" like experience and compose in the functionality that's only necessary for your application.

We've been experimenting with a hooks base approach that allows you to add things like sorting, filtering, and selection. Meaning, you can spare a little bit on bundle size by including only the things you want.

Stay tuned, when we're ready, we'll provide a more in-depth post on using the table component in the future!

Field

This component is the next iteration in supporting form based scenarios.

If you recall my previous post on using Fluent UI React v9 with Formik and Yup, I had to implement my own "ErrorText" component to handle the validation UX.

Fluent UI React v9 with Formik and Yup

Paul Gildea ・ Jul 15 ・ 3 min read

#fluentui #webdev #react #tutorial

Now with the addition of the Field component, that validation UX is provided straight out of the UI library.

Coming up, an updated post once field hits stable. For more details on the rest of the preview components, head over to: https://react.fluentui.dev

Fluent UI React v9 at Ignite 2022

This year, I had the opportunity to demo a Teams App leveraging Fluent UI React v9 to extend it across M365 to Outlook and Office.com.

Be sure to check out the breakout session, from low code to pro code: building and buying collaborative apps to power an evolving workplace to see Fluent UI React v9 in action.

Microsoft Ignite

Save the date and explore the latest innovations, learn from product experts and level up your skillset – join us to help shape the future of tech.

ignite.microsoft.com

If you've reached the bottom of this post, thank you! Our team is proud of the work put in this month and we welcome your feedback.

Have questions? Don't hesitate to reach out on:

GitHub: https://github.com/microsoft/fluentui
Docs: https://react.fluentui.dev
Twitter: https://twitter.com/fluentui

Enjoy!

Fluent UI React Component Lifecycle

Paul Gildea — Mon, 17 Oct 2022 17:58:36 +0000

The high level process

When developing components for Fluent UI React v9, each component passes through a series of development phases and then is finally released in the UI Library.

It's broken down into 3 distinct phases: Research, Unstable, Stable

Next we'll break down each phase into more detail.

🔍 Research

During the Research phase, Engineering partners with Product and Design to understand the scope of the component features, audit other UI libraries for industry standard patterns, and scaffold out the API.

The main criteria for going into the Research phase is:

A scaffolded/prototyped component within the defined feature scope
Relative high confidence estimation on when the component will reach the next phase on a quarter boundary

The thought process here is that during the Research phase, Engineering has prototyped and discovered a majority of the boundaries of the component. This gives us a higher confidence estimation so that partner teams can dependency plan for their own product work.

⚠️ Unstable

The main criteria for moving from Research to an Unstable component is:

Component exported via the unstable deep import
Component has a majority of the feature set complete, but may still be added or removed
Relative high confidence estimation on when the component will reach the next phase on a quarter boundary

During the Unstable phase, our engineers continue to partner with Design and Product to make sure the component meets a high bar for quality and has the right features. Part of that may include some unannounced API removals so teams should proceed with extreme caution before adopting an unstable component. We generally recommend against shipping these it to production.

Unstable doesn't mean the component is low quality. It's where we "battle test" it within a real Product to ensure it meets the needs or our stake holders.

Feeling up to adopting an unstable component? Great! Take steps to ensure breaking changes don't get shipped to your users, and let us know so we can form a tight feedback loop.

🎉 Stable

During the Stable phase, Engineering finalizes with Design and Product for the delivery of the component. This means that the component is ready to be used by any developers, has a stable API, has been validated for accessibility, and is exported in the UI library. The component is essentially "done" and ready for prime time.

The main criteria for moving from Unstable to Stable phase is:

Component exported from the top level of the UI library
Component is design and feature complete
Future API changes will occur according to semver
Component can be used in Production
The component has gone through a long list of testing

Essentially the component is ready to be used.

Estimation and Timelines

So if you were doing the math, the team tends to estimate component completion from start to finish for roughly 2 quarters. This is highly dependent on the complexity of the component, but that gives partner teams enough time to plan and sets expectations on timelines. We also check-in mid-quarter to notify any changes to the schedule as that should give runway to adapt to any changes.

This is just an overview of the general process and requirements, but if you want to get into some of the details, check out the work that's gone into the Card component epic.

If you're reading the bottom of this post, thank you! Our team wants to hear your feedback.

If you have any questions, don't hesitate to reach out on:

GitHub: https://github.com/microsoft/fluentui
Docs: https://react.fluentui.dev
Twitter: https://twitter.com/fluentui

Enjoy!

Fluent UI Insights EP3: Griffel

Paul Gildea — Mon, 19 Sep 2022 17:08:43 +0000

Fluent UI Insights is a series that describes the design and decisions behind the Fluent UI design system.

In the third episode, Oleksandr from the Fluent UI team explains the implementation details and complexities behind Griffel. Griffel is a CSS-in-JS used in Fluent UI React v9 and features ahead-of-time compilation.

In this video he covers:

Requirements for styling solution
Important concepts of Atomic CSS-in-JS
Creating Griffel CSS-in-JS
Did it all magically go smoothly? Find out more!

Checkout the CodesandBox from the video that demonstrates LVFHA order importance:

As always let us know what kind of content you want see from Fluent UI React by visiting us on:

GitHub: https://github.com/microsoft/fluentui
Docs: https://react.fluentui.dev
Twitter: https://twitter.com/fluentui

Fluent UI Insights EP2: Styling

Paul Gildea — Fri, 26 Aug 2022 18:30:00 +0000

Fluent UI Insights is a series that describes the design and decisions behind the Fluent UI React. In the second episode, Fluent UI Engineers Shift and Miro explain issues related to styling UI controls by sharing the requirements and also describing problems with existing solutions.

In this video they cover:

CSS
CSS specificity
BEM, CSS, CSS-in-JS
The current state of things
What's coming next with CSS-in-JS

As always let us know what kind of content you want see from Fluent UI React by visiting us on:

GitHub: https://github.com/microsoft/fluentui
Docs: https://react.fluentui.dev
Twitter: https://twitter.com/fluentui

What's new with Fluent UI React v9?

Paul Gildea — Tue, 02 Aug 2022 15:18:58 +0000

After nearly two years in development, we are proud to announce the release of Fluent UI React v9 to stable version 9.0! Fluent UI React v9 is a collaboration between the Teams and Office team.

This release provides a stable architecture for teams to build on and a baseline set of components to use. We have more components to build that will be coming in future. Check out what we have so far and give us feedback on our documentation site https://react.fluentui.dev/. And, let us know what components you're looking for on GitHub https://github.com/microsoft/fluentui.

Now, let's take a look at some of the top-level library features.

Performance

CSS-in-JS engine provides styling performance improvements

Fluent UI React v9 is leveraging Griffel, (https://aka.ms/griffel) our recently open-sourced CSS-in-JS implementation. It provides near zero runtime, SSR support, and optional build time transforms to improve performance. When using Griffel, partner teams have seen render time improvements over Fluent UI React v0 and v8.

Griffel is a CSS-in-JS with near-zero runtime, SSR support and styles defined with JavaScript objects.

🚀 With a zero config start, Griffel has both runtime & build time implementations
🔥 Optional build time transforms to improve performance
💪 Type-safe styles via csstype
🧩 Uses Atomic CSS to reuse styles and avoid specificity issues with CSS
📝 Experimental CSS extraction with Webpack plugin
🐞 Debug using Griffel DevTools extension

Lighter weight DOM

When building the components for Fluent UI React v9, DOM node depth was taken into consideration as primitive components are often used in more complex UX. For example, the v9 Avatar component when compared to the v8 Persona and PersonaCoin components has 50% fewer DOM elements to represent the same output. These extra nodes add up as you use them in more complex and repeated scenarios like virtualized lists where every millisecond counts.

Accessibility

When designing and building the components for Fluent UI React v9, accessibility was also taken into consideration from the start. Here are the ways the product is built to meet WCAG 2.1 specifications today:

Each component design spec takes into account keyboard, narrator, and high contrast definitions and each component goes through an extensive manual a11y test pass
Where possible components are using native elements to minimize the over use of ARIA
Components support high contrast out of the box

And here are some new A11y improvements specific in v9:

Splitbutton automated test errors and screen reader bugs are fixed in v9
Slider now works across both desktop and mobile screen readers
v9 includes a select component wrapping the native element
Support reduced animation user settings

Customization

Slots

Fluent UI React v9 internal parts of a component are called "slots." Think of the icon in a button.

Each component slot is exposed as a top-level prop of the same name. A button has an "icon" prop for working with the icon slot. All anatomies specified in Fluent UI's design and engineering specs are available as slots.

Fluent UI's component design allows full control over every slot in every component through the slot API. This allows you to customize by:

Passing content
Passing props
Changing the slot type
Replacing the slot entirely

Check out this deep dive on slots in this previous post:

Using Slots with Fluent UI React v9

Paul Gildea ・ Jul 8 '22

#fluentui #webdev #tutorial #react

Design to code

Theming support with design tokens

Fluent UI React theming is supported by design tokens defined in the Fluent Design System. Design tokens provide a common set of semantic key/value pairs that represent the design language. This includes concepts like color palettes, typography ramps, radius ramps, spacing, etc. These are defined at the design system level allowing UI Kits and UI libraries to easily update the design language into the respective solution.

The core design team has been working with the design community to provide Fluent based components that are designed to meet the needs of M365 products out of the box without the need for many style overrides. This becomes especially helpful when we share and integrate products within each other.

By leveraging these tokens, it's possible to provide a default web and Teams branded themes for:

Light mode
Dark mode
High contrast

Check out this quick start post on branding light and dark modes:

Quick branded light and dark modes with Fluent UI React v9

Paul Gildea ・ Jun 23 '22

#fluentui #javascript #webdev #tutorial

Migration

As you can see, Fluent UI React v9 is a new UI library that has substantial improvements over v8 and v0 in the areas of performance, accessibility, customization, and design to ode. These improvements couldn't have been accomplished in a simple backwards compatible manner, so migration from v0 or v8 to v9 will take some effort.

The good news is that we're here to help you with your upgrade, check out the Upgrading section of our documentation site for tips on getting started.

It covers topics like:

Component mapping and renames
Color mappings between theming interfaces
Component shims

Note, that in some cases it's not just a straight port of existing style overrides. The goal of the new design updates is minimizing the need of style overrides.

Also, you can find component specific migration documentation within our GitHub repository that's co-located to the source code. So, if you're looking for Avatar specific guidance, you can find it here: https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-avatar/MIGRATION.md

We'd love to hear from you!

If you're reading the bottom of this post, thank you! Our team is very proud of the work put into this release and we want to hear your feedback.

If you have any questions, don't hesitate to reach out on:

GitHub: https://github.com/microsoft/fluentui
Docs: https://react.fluentui.dev
Twitter: https://twitter.com/fluentui

Enjoy!

Creating Custom Variants with Fluent UI React v9

Paul Gildea — Mon, 25 Jul 2022 15:55:33 +0000

There are some cases in which you'll want to build a UI component variant to promote coherent UX across a product or a team of engineers. Quite often, this happens by overriding the default behaviors of the UI components available in your respective UI library, so you don't have to reinvent the wheel.

This scenario is no different with Fluent UI React. We've designed the UI components to allow style overrides. The following examples will walk you through the various ways you can use CSS-in-JS to override the default styling of the UI Components and create custom variants for your application.

Variant Scenario: Launch Button

So, for this example, we're creating a "Launch Button" that has a specific set of styling that overrides the default Button provided by Fluent UI React. We want to keep all the built-in functionality of the Button and override the following:

Always change the shape to be circular
Always have a Rocket Icon
Always change the background color of the rest, hover, and pressed states
Always is a large size

Here's an example of what we want the "Launch Button" to look like:

You'll notice that the overrides are always present—meaning our intent is that any consumer of this component isn't meant to be overridden themselves, thus promoting coherent UX across our theoretical product 😊.

In the next sections, we'll cover various ways we can override the Fluent UI React Button component and ways to structure it for sharing across a project.

Option 1: Create CSS style overrides and component props

The first option for creating a variant would be creating CSS-in-JS style overrides and configuring the props of the Button component. Let's look at defining the CSS-in-JS style overrides using Griffle—the default CSS-in-JS engine in Fluent UI React:



const useLaunchButtonStyles = makeStyles({
  launchButton: {
    backgroundColor: "#ce000a",
    ...shorthands.borderColor("transparent"),
    color: tokens.colorBrandBackgroundInverted,
    ":hover": {
      backgroundColor: "#b10007",
      ...shorthands.borderColor("transparent"),
      color: tokens.colorBrandBackgroundInverted
    },
    ":hover:active": {
      backgroundColor: "#5d0b00",
      ...shorthands.borderColor("transparent"),
      color: tokens.colorNeutralForegroundOnBrand
    }
  }
});

We've created CSS-in-JS style definitions that overrides the backgound-color, border-color, and color attributes of the Button style. We also did this for the rest, hover, and pressed states o the button.

Next, we'll use the styles hook we created and apply the class to the Button component via the className prop:



const l = useLaunchButtonStyles();

<Button className={l.launchButton}>Launch</Button>

Now, this only overrides the color of the Button component, which means we need to add the Rocket Icon and change the Button shape and size:



const l = useLaunchButtonStyles();

<Button className={l.launchButton}
  icon={<RocketRegular />}
  shape="circular"
  size="large">
  Launch
</Button>

So, now we have a "Launch Button." The downside is that we need to tell any consumer that they need to configure the Button component with a CSS class, an Icon, and a Shape. This means that potential consumers could either change the design or misconfigure the component to promote a consistent UX.

Let's see how we can solve this with our next option!

Option 2: Wrapper Component with style overrides and prop configuration

For this approach, we'll do exactly what we did in Option 1 above, but we'll wrap that up in a React Component.

Note: This technique does create a virtual node, so it's not recommended to have many layers of component wrapping as that can create performance issues. For cases of simple overrides not wrapped many times over, this approach meets our needs.

Once again, we'll take the same steps we did in Option 1, but wrap that up in a React Functional Component:



const useLaunchButtonStyles = makeStyles({
  launchButton: {
    backgroundColor: "#ce000a",
    ...shorthands.borderColor("transparent"),
    color: tokens.colorBrandBackgroundInverted,
    ":hover": {
      backgroundColor: "#b10007",
      ...shorthands.borderColor("transparent"),
      color: tokens.colorBrandBackgroundInverted
    },
    ":hover:active": {
      backgroundColor: "#5d0b00",
      ...shorthands.borderColor("transparent"),
      color: tokens.colorNeutralForegroundOnBrand
    }
  }
});

const LaunchButton: React.FC<LaunchButtonProps> = () => {
  const l = useLaunchButtonStyles();
  return (
    <Button
      icon={<RocketRegular />}
      className={classes}
      shape="circular"
      size="large"
    >
      Launch
    </Button>
  );
};

export default LaunchButton;

Now, when a consumer imports the LaunchButton they get all the consistency wrapped up into a functional component:



<LaunchButton />

This works great in guaranteeing coherent UX across a product, but we've essentially taken away any further downstream customization to consumers. If this was your intent—you're done. Yay! 🎉

But, let's pretend someone on your team says, "The Design team wants this feature to have a green "Launch Button" in this one specific feature. How can we do that?"

Well, you could create another wrapper component and call it LaunchButtonGreen. However, as you imagine more and more color requests in the future, you know this isn't scalable. So, let's leverage the existing styling capabilities in the Fluent UI React components and bring that to your variant.

In the next option, we'll look at allowing CSS-in-JS style overrides to let consumers control the color of the LaunchButton but keep everything else fixed.

Option 3: Wrapper component with overrides and allowing consumer style overrides

Now, we'll build on everything we've done in Option 2, but we'll allow consumers of the LaunchButton to pass style overrides via the className prop (just like we did with the Fluent UI React Button).

The interesting requirement we need to think about here is the order of the style overrides being applied. We'll leverage the mergeClasses API in Griffel which merges and dedupes the atomic classes generated by makeStyles API.

And, because order is important for mergeClasses we'll make sure consumer styles passed in via the className prop always win over the default LaunchButton styles:



const useLaunchButtonStyles = makeStyles({
  launchButton: {
    backgroundColor: "#ce000a",
    ...shorthands.borderColor("transparent"),
    color: tokens.colorBrandBackgroundInverted,
    ":hover": {
      backgroundColor: "#b10007",
      ...shorthands.borderColor("transparent"),
      color: tokens.colorBrandBackgroundInverted
    },
    ":hover:active": {
      backgroundColor: "#5d0b00",
      ...shorthands.borderColor("transparent"),
      color: tokens.colorNeutralForegroundOnBrand
    }
  }
});

export type LaunchButtonProps = Pick<
  React.HTMLAttributes<HTMLElement>,
  "className"
>;

const LaunchButton: React.FC<LaunchButtonProps> = ({ className }) => {
  const l = useLaunchButtonStyles();
  const classes = mergeClasses(l.launchButton, className);

  return (
    <Button
      icon={<RocketRegular />}
      className={classes}
      shape="circular"
      size="large"
    >
      Launch
    </Button>
  );
};

export default LaunchButton;

Here's an usage example from a consumer overriding the LaunchButton styles:



const useLaunchButtonOverrides = makeStyles({
  overrides: {
    backgroundColor: "green"
  }
});

const o = useLaunchButtonOverrides();

<LaunchButton className={o.overrides} />

Now, your variant has a similar developer experience as any other Fluent UI React component—a beautiful thing! It also gives the consumer a nice balance of customization and control over UX qualities that need to be coherent and consistent.

Want to know more? Checkout the CodesandBox for the full sample:

Let us know what kind of content you'd like to see from Fluent UI React by visiting us on:

GitHub: https://github.com/microsoft/fluentui
Docs: https://react.fluentui.dev
Twitter: https://twitter.com/fluentui

Thanks!

Fluent UI Insights EP1: Positioning

Paul Gildea — Fri, 22 Jul 2022 17:06:00 +0000

Recently, Oleksandr on the Fluent UI React team released a deep dive video on Positioning UX. It's our first episode in a video series we're experimenting with to see how folks want to learn more about the UX library.

I've linked the video below and as always let us know what kind of content you want see from Fluent UI React by visiting us on:

GitHub: https://github.com/microsoft/fluentui
Docs: https://react.fluentui.dev
Twitter: https://twitter.com/fluentui

Thanks!

Fluent UI React v9 with Formik and Yup

Paul Gildea — Fri, 15 Jul 2022 16:23:27 +0000

This post was inspired by the documentation examples from the Formik documentation.

This tutorial assumes that you have some previous experience working with Formik and Yup. If you are, then this becomes an exercise of mapping formik props to corresponding Fluent UI React Components.

This tutorial will cover high-level usage of Formik, but it's recommended you go read through the documentation to learn more.

1. Install the necessary dependencies

For this example, it's recommended that you install the following npm dependencies:

npm install formik handling form data
npm install yup for value parsing and validation
npm install @fluentui/react-components - for Form components
npm install @fluentui/react-icons - for icons

2. Build out your Form

For this example we're building the following login experience and will break down composing the UI and adding in the Formik and Yup validation:

Compose the form layout with CSS-in-JS

We start off with the high-level layout of the form leveraging Griffel, the CSS-in-JS engine that comes with Fluent UI React.

Let's start off using CSS Flexbox to lay everything out in a vertical stack with a maximum width of 480px:



const useStyles = makeStyles({
  form: {
    display: "flex",
    flexDirection: "column",
    maxWidth: "480px"
  }
});

Apply it to our UI using the className prop on the form.



export default function App() {
  const c = useStyles();
  return (
    <FluentProvider theme={webLightTheme}>
        <form className={c.form}>
        </form>
    </FluentProvider>
  );
}

Add in Fluent UI React Components

We'll be using the Input, Label, and Button components.

Also I created a small little ErrorText component to help display the error messages after validation.



export default function App() {
  const c = useStyles();
  const inputId = useId("input");
  const passId = useId("pass");
  return (
    <FluentProvider theme={webLightTheme}>
        <form className={c.form}>
          <Label htmlFor={inputId} required>
          Email
          </Label>
          <Input
            id={inputId}
            name="email"
            placeholder="hello@fluentui.dev"
          />
          <ErrorText />
          <Label htmlFor={passId} required>
          Password
          </Label>
          <Input
            id={passId}
            name="password"
            type="password
           />
          <ErrorText />
          <Button appearance="primary" type="submit">
          Login
          </Button>
        </form>
    </FluentProvider>
  );
}

3. Add in Formik and Yup

Finally add in Formik for handling the form data and Yup for creating your form parsing and validation.

Declare your Yup validation

Let's set up simple validation for the email and password entries.



const validationSchema = yup.object({
  email: yup
    .string()
    .email("Enter a valid email")
    .required("Email is required"),
  password: yup
    .string()
    .min(8, "Password should be of minimum 8 characters length")
    .required("Password is required")
});

Declare Formik initial values, assign the validation, and define your submit action

For this example, onSubmit will just alert the values of the form, but you can imagine this could call any backend service.



const formik = useFormik({
  initialValues: {
    email: "",
    password: ""
  },
  validationSchema: validationSchema,
  onSubmit: (values) => {
    alert(JSON.stringify(values, null, 2));
  }
});

Map Formik props to Fluent UI React Components

This one is pretty straightforward in that you simply match the up the Formik prop with Fluent UI React Component prop.



<form onSubmit={formik.handleSubmit}>
  <Input 
    value={formik.values.email}
    onBlur={formik.handleBlur}
    onChange={formik.handleChange}
  />
  ...
  <Button appearance="primary" type="submit">Login</Button>
</form>

You should get the idea here.

As always, here's the complete CodesandBox:

Finally, be sure to check out the ErrorText Component. It's just a React Functional Component with some CSS-in-JS, Design Tokens, Fluent UI React Icons, and HTML.

Let us know what other code examples you want to see and feel free to reach out to the team!

GitHub: https://github.com/microsoft/fluentui
Docs: https://react.fluentui.dev
Twitter: https://twitter.com/fluentui

Thanks!

Using Slots with Fluent UI React v9

Paul Gildea — Fri, 08 Jul 2022 18:50:26 +0000

Fluent UI React v9 components have customizable parts called "slots." An example of this is the icon slot of a Button which lets you supply an icon to the Button component.

Each component has top-level prop(s) for each supported slot(s). For example, Button has an icon slot, while Input has a root, contentBefore, and contentAfter slots.

Slots are an integral part of a component's design and we refer to it as the component's anatomy.

The following is a basic example of the Button anatomy:

In the above example, you can see how there's a slot allocated for icon content that sits next to the textual content of the Button.

The slots API give you full control over the slot allowing you to:

Pass content like text, images, and JSX
Pass props for state, classes, and event handlers
Change the type of the slot
Change the slot entirely

The next set of examples will demonstrate how to customize the icon slot on the Button component, but the same patterns can be used on any of the slots across the component library.

Passing text, images, and JSX to slots

The easiest way to pass content to a slot is to do it directly.

Passing text/emoji to a Button icon slot

JSX:



<Button icon="🚀">Launch</Button>

HTML output:



<button type="button">
  <span>🚀</span>Launch
</button>

Passing image/svg to a Button icon slot

In this example we are using a wrapped SVG icons from @fluentui/react-icons
JSX:



<Button icon={<RocketRegular />}>Launch</Button>

HTML output:



<button type="button">
  <span>
    <svg>...</svg>
  </span>Launch
</button>

Passing JSX to a Button icon slot

JSX:



// Just a basic count down timer
const [countDown, updateCountDown] = React.useState(10);
  setTimeout(() => {
    if (countDown > 0) {
      updateCountDown(countDown - 1);
    } else {
      updateCountDown(10);
    }
  }, 1000);

<Button icon={<CounterBadge color="danger" count={countDown} />}>Launch</Button>

HTML output:



<button type="button">
  <span>
    <div>10</div>
  </span>Launch
</button>

You can find the combined example on CodeSandbox:

Passing props for state, CSS classes, and event handlers

When you need to pass more than just content to a slot, you can leverage the object notation to pass props. Those props are added to the slot itself, as opposed to the content that goes inside the slot.

For the content that gets passed in the slot you use the children prop that can accept primitive values, JSX, and a render function.

Passing data with the data props

JSX:



<Button
  icon={{
    children: "🚀",
    "data-foo": "bar"
  }}>
    Launch
</Button>

HTML output:



<button type="button">
  <span data-foo="bar">🚀</span>Launch
</button>

Passing CSS classes with className prop

Note: This example is using Griffel a CSS-in-JS engine that's used with Fluent UI React v9.

JSX:



const useStyles = makeStyles({
  slotBackground: {
    backgroundColor: tokens.colorBrandBackground,
    ...shorthands.borderRadius(tokens.borderRadiusCircular)
  }
});

const App = () => {
  const c = useStyles();
  return <Button
          icon={{
            children: "🚀",
            className: c.slotBackground
          }}>
          Launch
         </Button>
}

HTML output:
Note: Griffel will generate atomic CSS



<button type="button">
  <span class="...">🚀</span>Launch
</button>

Passing event handlers

In this example the event handlers are attached to the slot itself and not the content. So the counter will start when the mouse enters the slot and will stop when the mouse leaves the slot.

JSX:



const [countDown, updateCountDown] = React.useState(10);
const [count, setCount] = React.useState(false);

setTimeout(() => {
  if (count) {
    if (countDown > 0) {
       updateCountDown(countDown - 1);
    } else {
      updateCountDown(10);
    }
  }
}, 1000);

const onStartCounter = (ev: React.MouseEvent<HTMLButtonElement>) => {
  setCount(true);
};
const onStopCounter = (ev: React.MouseEvent<HTMLButtonElement>) => {
  setCount(false);
};

<Button
  icon={{
    children: <CounterBadge color="danger" count={countDown} />,
    onMouseEnter: onStartCounter,
    onMouseLeave: onStopCounter
  }}>
  Launch
</Button>

HTML output:



<button type="button">
  <span onMouseEnter="..." onMouseLeave="...">
    <div>10</div>
  </span>Launch
</button>

You can find the combined example on CodeSandbox:

Change the type of the slot

In the case of Button the icon slot is by default a span element. If you need to change the type of the slot you can use the same object notation and specify the type with the as property.

JSX:



<Button
  icon={{
    as: "a",
    href: "#launch",
    children: "🚀"
  }}>
  Launch
</Button>

HTML output:



<button type="button">
  <a href="#launch">🚀</a>Launch
</button>

However, in most cases you might find yourself wanting to change the type of the component itself. Which is achieved the same way leveraging the top level as prop on the component - because the component is a slot itself. Common use cases are for changing a Button to an anchor for navigational purposes like with react-router.

JSX



<Button as="a" icon="🚀">Launch</Button>

HTML output:



<a>
  <span>🚀</span>Launch
</a>

You can find the combined example on CodeSandbox:

Change the slot entirely

There are times where you many need to change the entire slot including its containing element.

This is an escape hatch in the slots API, so it's highly recommended to leverage techniques whenever possible.

Handing off the computed props that would have been applied to the slot is critical to being able to handle every slot override case conceivable. Without it, there are computed values locked in the component that the consumer cannot access when doing a replacement or augmentation, such as styles and states they may need to handle. An example of this is open state in an Accordion item, which is calculated by the Accordion parent and handed to the item.

So keep that in mind if you head down this path 😊.

JSX:



<Button
  icon={{
    children: (Icon, iconProps) => {
      return "🚀";
    }
  }}>
  Launch
</Button>

HTML output:



<button type="button">
  🚀Launch
</button>

You can find the combined example on CodeSandbox:

So there you have it. A whirlwind of use cases for customization with slots.

Check out the documentation to learn more about slots.

If you want to learn more about Fluent UI React v9 reach out to us via:

GitHub: https://github.com/microsoft/fluentui
Docs: https://react.fluentui.dev
Twitter: https://twitter.com/fluentui

Enjoy!

Quick branded light and dark modes with Fluent UI React v9

Paul Gildea — Thu, 23 Jun 2022 07:28:17 +0000

When building Teams Apps, Office Add-ins, or any kind of Microsoft 365 integration there's always a balance of retaining your apps brand and aligning with the hosting apps UX.

However, if you are building an experience and your app maybe only has a brand color, then I'd recommend aligning with the hosting application UX so that your end customers have a consistent experience using your add-in, extension, or app.

This can be easily achieved by using the brand theming capabilities with Fluent UI React v9.

The library comes with light mode and dark modes built in with the ability to supply your own brand variants.

1. Create a `BrandVariants` object

The BrandVariant interface is just a color palette of 16 stops. There are tools available to create color palettes (which we are looking to make that easier in the future.) but for this example I've created a simple one here:

const myBrand = {
"10":"#000000",
"20":"#011800",
"30":"#002700",
"40":"#00360c",
"50":"#004612",
"60":"#005618",
"70":"#00671f",
"80":"#007826",
"90":"#218935",
"100":"#3e9949",
"110":"#59a85e",
"120":"#73b776",
"130":"#8ec68f",
"140":"#aad5a9",
"150":"#c6e4c5",
"160":"#e2f2e2"
};

2. Create a light and dark theme

Once you have your custom BrandVariants object, then you simply create a light theme and a dark theme calling createLightTheme and createDarkTheme respectively.

const light = createLightTheme(myBrand);
const dark = createDarkTheme(myBrand);

3. Pass your `Theme` to the `FluentProvider`

Now that you have a light and dark theme, you can pass that into the FluentProvider for your application and all the components within that scope will pick up colors from the custom BrandVariants.

<FluentProvider theme={light}>
  <Button appearance="primary">Button</Button>
  <Switch defaultChecked label="Switch" />
  <TabList defaultSelectedValue="tab1">
    <Tab value="tab1">Tab 1</Tab>
    <Tab value="tab2">Tab 2</Tab>
    <Tab value="tab3">Tab 2</Tab>
  </TabList>
  <Slider defaultValue={50} />
</FluentProvider>

The best part here is that Fluent UI React v9 will apply the BrandVariants values across the components in the rest, hover, and pressed states so that you don't need override each component individually.

So there you have it. A quick way to create light and dark mode support with a splash of brand color for your Microsoft 365 apps, add-ins, and extensions.

As always, you can find the full CodesandBox here:

For more on Fluent UI React v9:

GitHub: https://github.com/microsoft/fluentui
Docs: https://react.fluentui.dev
Twitter: https://twitter.com/fluentui

Enjoy!

Getting Started with Fluent UI React v9

Paul Gildea — Wed, 15 Jun 2022 04:06:48 +0000

Fluent is an open-source, cross-platform design system that gives designers and developers the frameworks they need to create engaging product experiences—accessibility, internationalization, and performance included.

Fluent UI React v9 is the UI library focused on React development for Microsoft 365 platforms like Teams Apps, Office Add-ins, and even stand along web app development.

The following is quick tutorial to get you up and running with the latest version of the library.

This tutorial assumes you have a React project up and running like Create React App and you are ready to add some UI components.

1. Install the npm package

Install the component suite package with your favorite package manager

npm

npm install @fluentui/react-components

yarn

yarn add @fluentui/react-components

2. Add a `FluentProvider` and `Theme`

A FluentProvider and a Theme are required for providing the right visual context for the UI Components so that they render properly. Without it, the components will not have any visuals.

import React from 'react';
import ReactDOM from 'react-dom';
import { FluentProvider, webLightTheme } from '@fluentui/react-components';

import App from './App';

ReactDOM.render(
  <FluentProvider theme={webLightTheme}>
    <App />
  </FluentProvider>,
  document.getElementById('root'),
);

3. Add Components

Fluent UI React v9 has two categories of components:

Stable - Components with stable APIs that will version according to Semantic Versioning. These are exported from the top level package.
Preview - Components with APIs that may change or may not have complete feature set. These components are exported out of the /unstable deep import

import React from 'react';
import ReactDOM from 'react-dom';
import { FluentProvider, webLightTheme, Button } from '@fluentui/react-components';
import { Select } from '@fluetui/react-components/unstable'; // Preview components deep import

ReactDOM.render(
  <FluentProvider theme={webLightTheme}>
    <Button appearance="primary">Hello World!</Button>
    <Select>
      <option>Red</option>
      <option>Green</option>
      <option>Blue</option>
    </Select>
  </FluentProvider>,
  document.getElementById('root'),
);

And that's all you need to get started using Fluent UI React v9.

Don't forget to check out https://react.fluentui.dev for more code samples and find out the latest on GitHub.

Lastly, here's a full CodeSandbox:

Enjoy!

DEV Community: Paul Gildea

Fluent Insights EP4: Slots

Using Slots with Fluent UI React v9

Paul Gildea ・ Jul 8 ・ 5 min read

What's new with Fluent UI React v9: October Update

Highlights

Migration shims

New components in stable

Dialog

New components in preview

Table

Field

Fluent UI React v9 with Formik and Yup

Paul Gildea ・ Jul 15 ・ 3 min read

Fluent UI React v9 at Ignite 2022

Microsoft Ignite

Fluent UI React Component Lifecycle

The high level process

🔍 Research

⚠️ Unstable

🎉 Stable

Estimation and Timelines

Fluent UI Insights EP3: Griffel

Fluent UI Insights EP2: Styling

What's new with Fluent UI React v9?

Performance

CSS-in-JS engine provides styling performance improvements

Lighter weight DOM

Accessibility

Customization

Slots

Using Slots with Fluent UI React v9

Paul Gildea ・ Jul 8 '22

Design to code

Theming support with design tokens

Quick branded light and dark modes with Fluent UI React v9

Paul Gildea ・ Jun 23 '22

Migration

Creating Custom Variants with Fluent UI React v9

Variant Scenario: Launch Button

Option 1: Create CSS style overrides and component props

Option 2: Wrapper Component with style overrides and prop configuration

Option 3: Wrapper component with overrides and allowing consumer style overrides

Fluent UI Insights EP1: Positioning

Fluent UI React v9 with Formik and Yup

1. Install the necessary dependencies

2. Build out your Form

Compose the form layout with CSS-in-JS

Add in Fluent UI React Components

3. Add in Formik and Yup

Declare your Yup validation

Declare Formik initial values, assign the validation, and define your submit action

Map Formik props to Fluent UI React Components

Using Slots with Fluent UI React v9

Passing text, images, and JSX to slots

Passing text/emoji to a Button icon slot

Passing image/svg to a Button icon slot

Passing JSX to a Button icon slot

Passing props for state, CSS classes, and event handlers

Passing data with the data props

Passing CSS classes with className prop

Passing event handlers

Change the type of the slot

Change the slot entirely

Quick branded light and dark modes with Fluent UI React v9

1. Create a BrandVariants object

2. Create a light and dark theme

3. Pass your Theme to the FluentProvider

Getting Started with Fluent UI React v9

1. Install the npm package

npm

yarn

2. Add a FluentProvider and Theme

3. Add Components

1. Create a `BrandVariants` object

3. Pass your `Theme` to the `FluentProvider`

2. Add a `FluentProvider` and `Theme`