Primer Components

React components for the Primer Design System

Documentation

Our documentation site lives at primer.style/components. You'll be able to find the information listed in this README as well as detailed docs for each component, our theme, and system props.

Installation

Install @primer/components in your project with npm:

npm install @primer/components

Usage

All of our components are exported by name from @primer/components, so you can import them with:

import {
  Box,
  Button,
  Heading,
  Text
} from '@primer/components'

Primer Components come with all the necessary CSS built-in, so you don't need to worry about including Primer CSS.

Base styles

You can establish base Primer styles for your app by wrapping all of your Primer components in <BaseStyles>:

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

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

This will set the color, font-family, and line-height CSS properties to the same ones used in primer-base.

Theming

Components are styled using Primer's theme by default, but you can provide your own theme by using styled-component's <ThemeProvider>. If you'd like to fully replace the Primer theme with your custom theme, pass your theme to the <ThemeProvider> in the root of your application like so:

import {ThemeProvider} from 'styled-components'

const theme = { ... }

const App = (props) => {
  return (
    <div>
      <ThemeProvider theme={theme}>
        <div>your app here</div>
      </ThemeProvider>
    </div>
  )
}

If you'd like to merge the Primer theme with your theme, you can do so importing the Primer theme and merging using Object.assign:

import {ThemeProvider} from 'styled-components'
import {theme} from '@primer/components'

const customTheme = { ... }


const App = (props) => {
  return (
    <div>
      <ThemeProvider theme={Object.assign({}, theme, customTheme)}> // matching keys in customTheme will override keys in the Primer theme
        <div>your app here</div>
      </ThemeProvider>
    </div>
  )
}

*Note that using Object.assign will only create a shallow merge. This means that if both themes have a color object, the entire color object will be replaced with the new color object, instead of only replacing duplicate values from the original theme's color object.

Static CSS rendering

If you're rendering React components both server-side and client-side, we suggest following styled-component's server-side rendering instructions to avoid the flash of unstyled content for server-rendered components. This repo's documentation template component demonstrates how to do this in Next.js.

Local Development

To run @primer/components locally when adding or updating components:

1. Clone this repo: git clone https://github.com/primer/components
2. Install dependencies: npm install
3. Run the dev app: npm start

👉 See the contributing docs for more info on code style, testing, and coverage.

Principles

• Everything is a component.
• Aim for total style encapsulation; don't rely on inheritance to provide default styles.
• Build small building blocks with minimal props to keep complexity low.
• Keep system constrained by only including props needed per component.
• Favor extending or wrapping components for more complex operations.
• Maintain design system consistency with utilities as props (for spacing, color, font-size, line-height, widths, and radii).