Site navigation

React

Get started using Primer React components in your React application.

Source

On this page

Getting started

Install @primer/react and its peer dependencies:

npm install @primer/react react react-dom styled-components @primer/primitives --save

Import and use @primer/primitives in your global CSS file

@import '@primer/primitives/dist/css/primitives.css';
@import '@primer/primitives/dist/css/functional/themes/light.css';
@import '@primer/primitives/dist/css/functional/themes/dark.css';

body {
  color: var(--fgColor-default);
  background-color: var(--bgColor-default);
}

Set the data-color-mode, data-light-theme, and data-dark-theme attributes on your html element. These will control the color mode and active theme for your application. To learn more about theming, check out our theming guide
```
<html lang="en" data-color-mode="auto" data-light-theme="light" data-dark-theme="dark">
  
</html>
```

Wrap the root of your application with ThemeProvider and BaseStyles:

import {ThemeProvider, BaseStyles} from '@primer/react'

function App() {
  return (
    <ThemeProvider>
      <BaseStyles>
        <div>...</div>
      </BaseStyles>
    </ThemeProvider>
  )
}

Import components from @primer/react and use them in your application:

import {Button} from '@primer/react'

function MyComponent() {
  return <Button>Click me</Button>
}

Polyfills & Browser Support

Primer React supports the current versions of Chrome, Firefox, Safari, and Microsoft Edge, as well as the Firefox Extended Support Release. This is consistent with GitHub's Browser Support.

Primer React does not transform code to support older ECMAScript versions (eg. ES5), and uses ECMAScript features like Object.assign and syntax features like native classes and Object destructuring and spreading.

Any environment that uses Primer React should have all the necessary polyfills installed to comply with the latest code standards, as Primer React does not ship with them. Additionally, as Primer React does not transform code to support older versions, it may be necessary for projects to transform the code if support for older browsers (such as Edge 18) is needed.

Peer dependencies

Primer React ships with a few libraries labeled as peer dependencies. These libraries are commonly already installed in host projects and installing multiple versions can introduce errors.

Primer React requires the following peer dependencies:

styled-components at version 5.0.0 or higher
react at versions 18.x or higher
react-dom at versions 18.x or higher

BaseStyles

In order to set baseline color, font-family, and line-heights across your project, you will need to establish base Primer styles for your app by wrapping all of your Primer components in <BaseStyles> at the root of your app:

import {BaseStyles, Box, Heading} from '@primer/react'

export default () => (
  <BaseStyles>
    <Box m={4}>
      <Heading as="h2" sx={{mb: 2}}>
        Hello, world!
      </Heading>
      <p>This will get Primer text styles.</p>
    </Box>
  </BaseStyles>
)

This will apply the same color, font-family, and line-height styles to the <body> as Primer CSS's base styles.

Static CSS rendering

If you're rendering React components both server- and client-side, we suggest following styled-component's server-side rendering instructions to avoid the flash of unstyled content for server-rendered components.

TypeScript

Primer React includes TypeScript support and ships with its own typings. You will still need to install type definitions for peer dependencies if you import them in your own application code.

Once installed, you can import components and their prop type interfaces from the @primer/react package:

import {Button, ButtonProps} from '@primer/react'

Fixing "Duplicate identifier 'FormData'"

In versions 4.1.19 and later, @types/styled-components declares a dependency on both @types/react and @types/react-native. Unfortunately, those declarations clash; for more information, see issue 33311 and issue 33015 in the DefinitelyTyped repo.

You may run into this conflict even if you're not importing anything from react-native or don't have it installed. This is because some package managers hoist packages to the top-level node_modules folder, and the TypeScript compiler automatically includes types from all folders in node_modules/@types by default.

The TypeScript compiler allows you to opt-out of this behavior using the typeRoots and types configuration options. The best solution for this error, at least for now, seems to be to opt out of the automatic inclusion of node_modules/@types and instead list the types you want to be included individually.

In your tsconfig.json, add to the types array under the compilerOptions like so:

{
  "compilerOptions": {
    "types": ["node", "react", "styled-components", "jest"]
  }
}

You'll need to customize the array based on the @types/ packages you have installed for your project.

Silencing warnings

Like React, Primer React emits warnings to the JavaScript console under certain conditions, eg. when using deprecated components or props. Similar to React, you can silence these warnings by setting the NODE_ENV environment variable to production during bundling.

Testing

Testing your application with Primer React is no different than testing your application with any other React library. Depending on your test environment and the testing libraries you use, you may need polyfills. For example, jest runs via Node runtime and uses JSDOM as a DOM implementation, meaning you will need to mock some browser APIs. We have helpers that can be used to mock some of these APIs. You can import the helpers in your test setup file like so:

import '@primer/react/test-helpers'

More information

See the primer/react repository for more information about how to use and contribute to Primer React. For component-specific documentation, check out the React section in the component's docs (example: ActionList).