1 | # [Fluent UI React](https://developer.microsoft.com/en-us/fluentui)
|
2 |
|
3 | **The React-based front-end framework for building web experiences.**
|
4 |
|
5 | [![npm version](https://badge.fury.io/js/%40fluentui%2Freact.svg)](https://badge.fury.io/js/%40fluentui%2Freact) [![Build Status](https://dev.azure.com/uifabric/fabricpublic/_apis/build/status/office-ui-fabric-react%20-%20PR?branchName=master)](https://dev.azure.com/uifabric/fabricpublic/_build/latest?definitionId=84&branchName=master)
|
6 |
|
7 | Fluent UI React is a collection of robust React-based components designed to make it simple for you to create consistent web experiences using the Fluent Design Language.
|
8 |
|
9 | ## Learn about Fluent UI
|
10 |
|
11 | [Fluent UI React current release documentation](https://developer.microsoft.com/en-us/fluentui)
|
12 |
|
13 | [Fluent UI Northstar documentation for Teams developers](https://aka.ms/fluent-ui)
|
14 |
|
15 | ## Who uses Fluent UI React?
|
16 |
|
17 | ![image](https://user-images.githubusercontent.com/785361/50458071-45b58d00-0915-11e9-90c0-ad8789c99db5.png)
|
18 |
|
19 | \+ 45 additional Microsoft sites and products
|
20 |
|
21 | ## For more information...
|
22 |
|
23 | Please see the [wiki](https://github.com/microsoft/fluentui/wiki).
|
24 |
|
25 | ## Contents
|
26 |
|
27 | - [Using Fluent UI React](#using-fluent-ui-react)
|
28 | - [Integrating in your project](#integrating-in-your-project)
|
29 | - [Version policy](#version-policy)
|
30 | - [Browser support](#browser-support)
|
31 | - [Right-to-left support](#right-to-left-support)
|
32 | - [Server-side rendering](#server-side-rendering)
|
33 | - [Advanced usage](#advanced-usage)
|
34 | - [Contribute to Fluent UI React](#contribute-to-fluent-ui-react)
|
35 | - [Building the repo](#building-the-repo)
|
36 | - [Testing](#testing)
|
37 | - [Advanced building tips](#advanced-building-tips)
|
38 | - [Licenses](#licenses)
|
39 | - [Changelog](#changelog)
|
40 |
|
41 | ## Using Fluent UI React
|
42 |
|
43 | ### Creating a new app
|
44 |
|
45 | To create a simple React app using [Create React App](https://create-react-app.dev), [install Node.js](https://nodejs.org), then run:
|
46 |
|
47 | ```sh
|
48 | npx create-react-app my-app
|
49 | cd my-app
|
50 | npm install @fluentui/react
|
51 | npm start
|
52 | ```
|
53 |
|
54 | See the next section for some starter code using Fluent UI React controls.
|
55 |
|
56 | ### Integrating in your project
|
57 |
|
58 | ```sh
|
59 | npm i @fluentui/react
|
60 |
|
61 | # Or, use yarn
|
62 | yarn add @fluentui/react
|
63 | ```
|
64 |
|
65 | This will add the package as a dependency in your `package.json` file and download it under `node_modules/@fluentui/react`.
|
66 |
|
67 | The library includes ES2015 module entry points under the `lib` folder (use `lib-amd` if you need AMD, or `lib-commonjs` if you need commonjs). To use a control, import it and then use it in your render method:
|
68 |
|
69 | ```jsx
|
70 | import React from 'react';
|
71 | import ReactDOM from 'react-dom';
|
72 | import { PrimaryButton } from '@fluentui/react/lib/Button';
|
73 |
|
74 | ReactDOM.render(<PrimaryButton>I am a button.</PrimaryButton>, document.getElementById('root'));
|
75 | ```
|
76 |
|
77 | ### Version policy
|
78 |
|
79 | Fluent UI React adheres to [semantic versioning](http://www.semver.org/). However, we only consider constructs directly importable at the package level or from files at the root (e.g. `@fluentui/react/lib/Utilities` or `@fluentui/react/lib-amd/Styling`) to be part of our API surface. Everything else is considered package-internal and may be subject to changes, moves, renames, etc.
|
80 |
|
81 | ### Browser support
|
82 |
|
83 | Fluent UI React supports all evergreen browsers, with IE 11 as the min-bar version of Internet Explorer. See the [browser support doc](https://github.com/microsoft/fluentui/wiki/Browser-Support) for more information.
|
84 |
|
85 | ### Right-to-left support
|
86 |
|
87 | All components can render in LTR or RTL, depending on the `dir` attribute set on the `html` element (`dir="rtl"` will flip the direction of everything). You can also use the `setRTL` API if you don't have control over the `html` element's rendering. Example:
|
88 |
|
89 | ```tsx
|
90 | import { setRTL } from '@fluentui/react/lib/Utilities';
|
91 |
|
92 | setRTL(true);
|
93 | ```
|
94 |
|
95 | ### Server-side rendering
|
96 |
|
97 | Fluent UI React components can be rendered in a server-side Node environment (or used in tests which run in an SSR-like environment), but it requires customizing how styles and SCSS files are loaded. See the [server-side rendering documentation](https://github.com/microsoft/fluentui/wiki/Server-side-rendering-and-browserless-testing) for examples of how to handle this.
|
98 |
|
99 | ### Advanced usage
|
100 |
|
101 | For info about advanced usage including module- vs. path-based imports, using an AMD bundler like RequireJS, and deployment features, see our [advanced documentation](https://github.com/microsoft/fluentui/wiki/Advanced-Usage).
|
102 |
|
103 | ## Contribute to Fluent UI React
|
104 |
|
105 | Please take a look at our [contribution guidelines](https://github.com/microsoft/fluentui/wiki/Contributing) for more info. Also read [Contribute bug fixes](https://github.com/microsoft/fluentui/wiki/Bug-Fixes) and [Contribute new component](https://github.com/microsoft/fluentui/wiki/New-Components).
|
106 |
|
107 | ## Building the repo
|
108 |
|
109 | Before you get started, **make sure you have read the [Git branch setup instructions](https://github.com/microsoft/fluentui/wiki/Setup)**
|
110 |
|
111 | To view the documentation including examples, contracts, component status, and to add functionality or fix issues locally, you can:
|
112 |
|
113 | 1. `git clone https://github.com/microsoft/fluentui.git`
|
114 | 2. `cd fluentui`
|
115 | 3. `yarn`
|
116 | 4. `yarn builddemo`
|
117 | 5. `yarn start`
|
118 |
|
119 | This will start a demo page from the `office-ui-fabric-react` package folder, which will open a web browser with the example page. You can make changes to the code which will automatically build and refresh the page using live-reload.
|
120 |
|
121 | To build and run tests for all packages in the repo, run `yarn build` from the root.
|
122 |
|
123 | To build individual packages within the `packages/*` or `apps/*` folders, `cd` to the relevant folder and run `yarn build`. Note that because the packages are symlinked together, you must manage building dependencies in the right order, or use the `yarn buildto` script to build to the specific package you want.
|
124 |
|
125 | #### Advanced build commands
|
126 |
|
127 | There are more advanced build commands listed in the [Build Commands](https://github.com/microsoft/fluentui/wiki/Build-Commands) wiki page.
|
128 |
|
129 | ### Testing
|
130 |
|
131 | For info about testing, see our [testing documentation](https://github.com/microsoft/fluentui/wiki/Testing).
|
132 |
|
133 | ## Licenses
|
134 |
|
135 | All files on the Fluent UI React GitHub repository are subject to the MIT license. Please read the License file at the root of the project.
|
136 |
|
137 | Usage of the fonts and icons referenced in Fluent UI React is subject to the terms of the [assets license agreement](https://aka.ms/fluentui-assets-license).
|
138 |
|
139 | ## Changelog
|
140 |
|
141 | We use [GitHub Releases](https://github.com/blog/1547-release-your-software) to manage our releases, including the changelog between every release. View a complete list of additions, fixes, and changes on the [releases](https://github.com/microsoft/fluentui/releases) page.
|
142 |
|
143 | ---
|
144 |
|
145 | This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
|
146 |
|
147 | > The **Office UI Fabric React** project has evolved into **Fluent UI React**! We have a lot in store for Fluent UI - [Read our announcement here](https://developer.microsoft.com/en-us/office/blogs/ui-fabric-is-evolving-into-fluent-ui/) and see more details about what this means for package consumers below.
|
148 |
|
149 | # [Fluent UI React](https://developer.microsoft.com/en-us/fluentui)
|
150 |
|
151 | **The React-based front-end framework for building experiences for Microsoft 365.**
|
152 |
|
153 | Fluent UI React ([formerly Office UI Fabric React](https://developer.microsoft.com/en-us/office/blogs/ui-fabric-is-evolving-into-fluent-ui/)) is a collection of robust React-based components designed to make it simple for you to create consistent web experiences using the Fluent Design Language.
|
154 |
|
155 | For information about available controls, see the [Fluent UI website](https://developer.microsoft.com/en-us/fluentui).
|
156 |
|
157 | To get started using or contributing to Fluent UI React, see the [full readme](https://github.com/microsoft/fluentui/blob/master/README.md).
|
158 |
|
159 | ## Moving to `@fluentui/react`
|
160 |
|
161 | Going forward, the `office-ui-fabric-package` will be renamed to `@fluentui/react`. The `@fluentui/react` package exists today as a mirror of `office-ui-fabric-react`'s public API surface. (Updates will still be published under both names for at least the duration of version 7.)
|
162 |
|
163 | If you'd like to start using `@fluentui/react` now, you can do so by changing your dependency and imports.
|
164 |
|
165 | Imports in either of these formats can be directly renamed:
|
166 |
|
167 | ```ts
|
168 | // Old
|
169 | import { TextField } from 'office-ui-fabric-react';
|
170 | import { TextField } from 'office-ui-fabric-react/lib/TextField';
|
171 |
|
172 | // New
|
173 | import { TextField } from '@fluentui/react';
|
174 | import { TextField } from '@fluentui/react/lib/TextField';
|
175 | ```
|
176 |
|
177 | However, deeper imports from internal files **will not** work with `@fluentui/react`. (These types of imports are also unsupported today, as internal file paths are considered private APIs and therefore subject to change without notice.)
|
178 |
|
179 | ```ts
|
180 | // Not supported currently; won't work with @fluentui/react
|
181 | import { TextField } from 'office-ui-fabric-react/lib/components/TextField/index';
|
182 |
|
183 | // Use instead
|
184 | import { TextField } from '@fluentui/react';
|
185 | import { TextField } from '@fluentui/react/lib/TextField';
|
186 | ```
|
187 |
|
188 | If you're currently depending on an API which you think should be public but is not exported from the top level of the package, please [file an issue](https://github.com/microsoft/fluentui/issues) to discuss.
|