Skip to content
Primer Design System

Primer Design System

On this page

React

Get started using Primer React components in your React application.
On this page

Dotcom Codespaces (staff-only)

Are you a GitHub employee (Hubber) looking to make a change to primer/react or another Primer library? Take a look at our documentation for the primerize tool (GitHub staff only), which can help get you started in a dotcom codespace.

Getting started

  1. Install @primer/react and its peer dependencies:

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

  2. 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>
      )
    }

  3. 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.

Minimizing bundle size

Module bundlers that use ECMAScript modules (ESM) will automatically tree-shake Primer React, ensuring that no unused code is included in your final bundle. However, if you're not using ESM, you may be able to drastically reduce the size of your final bundle by importing components individually from the lib subfolder:

// using import syntax
import Box from '@primer/react/lib/Box'
// using require syntax
const Box = require('@primer/react/lib/Box')

Note that the modules in the lib folder are CommonJS-style modules; if you're using ESM and a compatible module bundler, importing files individually from lib provides no benefit.

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 4.0.0 or higher
  • react at versions 17.x or higher
  • react-dom at versions 17.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/lib-esm/utils/test-helpers' // For ESM
import '@primer/react/lib/utils/test-helpers' // For CommonJS

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).