Fluent UI v8

[dzearing]

UPDATE Feb. 9: Target release date is February 22, or end of February at latest. See this comment detailing a few significant changes from the original beta version.

For current details of the release, please see the draft release notes and migration guide.

Remaining work is tracked here.

Expand for original content, preserved for reference but may be out of date.

Summary

The next release of Fluent UI React is going to be a little different than previous releases of this project and we wanted to help set expectations, detail some of its nuances, and set the stage for subsequent releases.

We view this next release as an incremental release that will set up customers, partners, and contributors for the team's collective vision of improving the baseline components used in all Microsoft 365 experiences. Going forward we will be making smaller, easy to consume, incremental releases of Fluent UI.

The Version 8 (v8) release will focus on:

1. This is an incremental release
   • No major visual changes
   • Limited API surface changes (mainly Button)
   • Package restructuring paves the way for smoother updates in the future
   • Intended to be an easy upgrade
2. Adds React Strict Mode Support
   • Unblocks the use of React Strict Mode while developing applications
   • Useful for testing out React Concurrent Mode
   • Converted several components to Function Components and removed deprecated lifecycle methods on the rest

All content in this issue is a work in progress and will not be final until we approach release.
Note: "v8" here refers to "version 8," not the v8 JavaScript engine.

~~New functionality available outside of Version 8. ~~
~~The Improved Button was part of the Version 8 release, but we found that it complicated the upgrade story, especially since the old button was still used in some other components. The same button is still available from @fluentui/react-button but has no longer replaced the default button. ~~

1. ~~Improved Button ~~
   • Smaller bundle size, better render perf
   • Introduction of design tokens and slots - looking for feedback!
   • Please see the @fluentui/react-button package README for details about improvements.

Timeline

Note: These dates are our best estimations.

Milestone	Date
v8 snap*	September 25, 2020
v8 beta release	October 19, 2020
v8 official release	Early 2021

*v8 snap: 7.0 branch is created. Fixes for v7 will need to go in 7.0 branch until beta release. After beta release, all fixes should go into master first then cherry-pick into 7.0 branch.

What's in v8?

We are currently tracking the related work here.

Below is a more detailed overview of upcoming changes in v8. Please note, these are still subject to change before official release. Comprehensive release notes will be provided when release happens.

# Packaging restructuring - pave the way for future updates

[Breaking] Package renaming office-ui-fabric-react to @fluentui/react

Starting in v8, you will need to install @fluentui/react@8 instead of office-ui-fabric-react@8. More details and migration tips here.

[Breaking] @uifabric to @fluentui package renames

If time allows, we plan to move our @uifabric packages to the @fluentui scope, and in some cases change the names to better align with current conventions. For packages used by the suite (@fluentui/react), we'll continue to publish aliases under the old @uifabric names (until their major version bumps) to prevent consumers from needing duplicate dependency versions. See this issue for details.

Change of plan: We decided to rename all the packages without aliases, but will provide a codemod to help pick up the renames.

Major version policy change for sub-packages

Starting with this release, sub-packages such as @uifabric/utilities or @uifabric/merge-styles will no longer move in major-lockstep with the suite: for each sub-package, unless it also has breaking changes, it will not major bump when the suite does.

The main benefit is that this will reduce duplicate dependencies for consumers who need a longer timeline to fully upgrade to the latest suite package version, and may have multiple versions of the suite in the same app bundle in the meantime.

Change of plan: We've decided to major bump all the packages for this release, but will try to get rid of major-lockstep next release. (This was due to technical challenges of renaming packages from @uifabric to @fluentui and getting rid of major-lockstep at the same time, as well as time constraints.)

# React Strict Mode Support

Full strict mode support for all components

• No usage of legacy React lifecycle APIs (UNSAFE_*)
• No usage of findDOMNode

[Breaking] Function component conversion

Most components are being converted from class components to function components (and the remaining components may be converted in a minor version). This work is being tracked here.

In general this will not result in a significant change to the component API surface. However, there are a few important implications, outlined in detail here.

Main points:

• Class extension of components is no longer supported (exception: Picker components, BaseComponent)
• Changes to how the ref prop works.
• ReactDOM.findDOMNode is not supported for function components (a React limitation).
• Directly accessing components' state is no longer supported
• More components properly implement controlled/uncontrolled behavior and standard onChange signatures

List of breaking changes

Please see the migration guide for a detailed list of breaking changes to individual components, including removal of certain props previously marked as deprecated.

Testing v8

The beta is now available on npm as @fluentui/react@beta. We encourage you to try it out and provide us with any feedback.

(Release notes and migration guide coming soon!)

Open questions v8 will answer before release

Question: How will customers upgrade from v7 to v8?

We will provide an upgrade-source script which will apply renames to your code. Symbols, imports, and prop renames will be adjusted automatically, and references to deprecated things which have no automated alternative will add comments and links to explanations.

Question: What is the right way to theme Fluent UI?

More details coming soon!

[Kesshi]

I have a question about the "Icons updated to svg" topic. Will icon fonts still be supported? In our application we replaced the fabric icon font with a custom one. We register some of the icons under the same name like the fabric ones so all the fluent-ui react controls are automatically using our icons. Also at runtime we make heavy use of the iconName feature. Our application is plugin based and we need to have access to the whole icon library at runtime because we don't know in advance which icon is used from the plugins. For us the current icon font solution is perfect. It would be nice if we can continue to use it (atleast with a custom font) in V8.

[kusing]

Are there any plans to take up the below issue to "Convert Fabric to use rem" as by using rem we respect user preference even helps to make the UI more accessible and responsive.
#6014

[khmakoto]

We should consider #9698 in here.

[dzearing]

@Kesshi Thanks for the callout on this - we'll need to be careful about how we roll this out to make sure we don't break your scenario; in the worst case scenario we will have an alternative way to keep this behavior so that you "opt in" to taking the bundle size hit. We want normal use cases to not be penalized by bundle size.

[ghost]

Will there be a browser usable release like this?
https://cdn.jsdelivr.net/npm/@fluentui/[email protected]/dist/fluentui-react.min.js

[abdullahsalem]

@dzearing Is Fleunt UI v8 equivalent to Fleunt UI v0?
I am a bit confused by seeing these two labels!

[vsspt]

Can you please confirm when will Fluent UI V8 be released to public, even if its a Beta version?
We are currently designing a new UI, and we would love to start using the V8 version as soon as possible!

Thank you!

[xugao]

@abdullahsalem - V0 is referring @fluentui/react-northstar. V8 is referring next version of @fluentui/react / office-ui-fabric-react

[xugao]

@vsspt -

We intend to release Fluent UI 8 in late summer 2020, and will be locking the feature changes by end of June.

We will provide update once we have something consumable

[PatoBeltran]

Will this version support the use of ReactDOMServer.renderToNodeStream(element) for server side rendering?

[Nemeczek]

The Charting package will be part of Fluent UI 8? BTW. I just created a project with V7 version, and so far the experience is excellent. The most satisfying surprise was how well TextField integrated with react-hook-form. Great stuff.

[it950]

In react-next package , some component styles has changed from css-in-js to scss file,
can you provide some suggestion on development ？
where the css should in? still use css-in-js or move to scss file?

[myermian]

• Converge on a single theme context for all components across current and northstar components
• Unify on css variables as a delivery mechanism for theme vlaues
• Backwards compat for existing use cases for loadTheme, Customizer.applySettings, Provider, and<Customizer ...>
  Question: What is the right way to theme Fluent UI?

Any update on that question?

Can we make the ability to themes apply to the entire site (page and components) more easy? It took me a long time to find an undocumented <Fabric applyThemeToBody> component, which sadly does not update the body based on theme changes after the initial page load. Something that is similar to how it is done in Azure DevOps would be nice.

[vsspt]

@dzearing, are there any news regarding the release date?

[las3r]

Will you include modifying the "theme generator" to let users choose their framework? With all of the different packages / variants of Fluent UI available it would be good for people to be able to choose what they want. I've already found some inconsistencies in the theme generator for the different versions (key differences etc). (https://fabricweb.z5.web.core.windows.net/pr-deploy-site/refs/heads/master/theming-designer/index.html)

[ecraig12345]

For anyone interested, we've just updated the issue description with the current plan including a specific release timeline.

[ecraig12345]

The issue description has been updated again with a higher-level summary of changes and some other additions.

[ecraig12345]

The version 8 beta is now available on npm as @fluentui/react@beta. Please try it out and let us know what you think! (Still working on an initial version of the release notes and migration guide but that should be ready soon.)

[ecraig12345]

"Beta" release notes and migration guide are now available. These are still somewhat subject to change before the final release. If you notice anything missing, please let us know.

[layershifter]

In general this will not result in a significant change to the component API surface. However, there are a few important implications, outlined in detail here.

Link is broken 😿

[ecraig12345]

@layershifter Links are fixed now.

[ecraig12345]

Version 8 release update

TL;DR: New target release date is February 22, or end of February at latest. Also, your version 7-style Button imports will now work without modification.

First of all, apologies for the delayed release and lack of updates. In addition to holiday-related delays, there have been some shifts around our approach to converging components with @fluentui/react-northstar that had an indirect impact on version 8. While these changes caused delays, we're confident that we're now on a better path overall for both our converged and existing components.

The overall short-term impact is actually that @fluentui/react version 8 is now more similar to version 7.

Button changes

For most consumers, the most impactful changes are around Button:

• We've returned to exporting the old Button by default, after convergence discussions showed that the new Button (@fluentui/react-button) is not production-ready quite yet
• As such, compat exports have been removed for now. (see Remove compat exports, move Button back to old location #16895)

Preview package and ThemeProvider changes

The main change directly resulting from convergence work is that @fluentui/react-button, @fluentui/react-theme-provider and @fluentui/react-compose have been moved back to "dev" status (not preview) while we make some refinements. This will have no impact on existing consumers who hadn't started experimenting with those new packages.

If you are currently directly consuming @fluentui/react-theme-provider and using it with @fluentui/react version 8, you should switch to import ThemeProvider related from @fluentui/react or @fluentui/react/lib/Theme instead. @fluentui/react-theme-provider will remain beta version and be actively updated with breaking changes after version 8 official release (similar to @fluentui/react-button).

Package structure changes

In the original beta version, most of the files from @fluentui/react were moved into @fluentui/react-internal and other packages. This has now been reverted.

For those who haven't started testing the beta yet, this will have no impact (and might make things easier when you do upgrade). The only negative impact should be for consumers who are using deep imports and had already started updating their deep imports as part of testing the beta.

• Most component files that were located within office-ui-fabric-react in version 7 have moved back to @fluentui/react.
  • Version 8 Checkbox, Link, Pivot, Slider, and Toggle have moved back to @fluentui/react from individual @fluentui/react-* packages
  • As a result, we were able to get rid of @fluentui/react-internal (most of the circular dependencies that required it have been removed) -- see Merge react-internal back into react #16832
• The component files from @fluentui/react-date-time (formerly @uifabric/date-time) have moved into @fluentui/react itself, and are re-exported from @fluentui/react-date-time.
  • Unless you're using deep imports, this should have no impact.
  • The move was needed to resolve a circular dependency, now that the newer (@fluentui/react-date-time) Calendar and DatePicker are exported from @fluentui/react by default.

[ecraig12345]

A few more updates...

The release likely won't be quite ready by Feb. 22, but it should be ready by the end of that week.

Today we published beta versions of all packages adding React 17 to peer dependencies range. We haven't been able to thoroughly test it yet due to tooling issues, so please file an issue if you encounter any React 17-specific bugs.

The following experimental components have been removed or deprecated from @fluentui/react-experiments (formerly @uifabric/experiments):

• Removed Button: didn't provide desired performance gains, and is superseded by convergence work. (Use Button from @fluentui/react until the converged version is ready.)
  • MicroFeedback now uses the button from @fluentui/react; this will affect valid slot prop overrides.
• Deprecated Slider: we kept this one for now since it provides some functionality not currently implemented by the @fluentui/react Slider, but it will also be superseded by convergence work in the future.
• Removed Toggle: superseded by convergence work. (Use Toggle from @fluentui/react until the converged version is ready.)

The previous experimental implementation of Card (which was never officially released) has been entirely removed from @fluentui/react-cards, which now exports the work-in-progress converged Card instead. If you were using the old Card, please file an issue and we can discuss possible approaches.

[ecraig12345]

Version 8 has now been officially released! 🎉 🎉 🎉

You can install it from npm using npm install @fluentui/react@^8.0.0.

I'm closing this issue now that the work is finished, but feel free to file new issues if you run into any problems.

Additions to release notes

For anyone who read through the release notes in the past and is interested in changes only, these are the main points that have been recently added.

Known issues

Azure theme

Azure theme styling for DatePicker and Calendar may not fully work - #17156

Calendar/DatePicker

Due to time constraints, we didn't add back the global classNames that were present for the office-ui-fabric-react 7 versions of these components. This will only affect people who were previously styling those components with classNames. More info at #15646 about alternative approaches.

New breaking changes to components

Checkbox

Checkbox no longer accepts arbitrary native props at the root (ICheckboxProps no longer extends React.ButtonHTMLAttributes<HTMLElement | HTMLInputElement>). This actually is not a behavior change: any native props or data-* props previously being passed through were ignored, and now the types accurately reflect the behavior.

To apply arbitrary native props to the hidden checkbox input element (used for accessibility and forms), use ICheckboxProps.inputProps instead. Note that data-* props are supported in ICheckboxProps.inputProps but will require casting since TS < 4.1 doesn't provide a way to express this. This should be adequate for most scenarios, but please comment on this issue if you have a scenario where you need native props on the root element.

ComboBox

The return type of IComboBox.focus() has changed from boolean to void to reflect its actual behavior (the implementation does not return a value and can't easily be modified to do so).

TextField

onChange is now called synchronously in the change event handler, before updating state (previously it was called asynchronously after the state update). This more closely matches other components and React itself, but may cause issues if anyone was depending on the old behavior.