Primer Components

React components for the Primer Design System

Status

⚠️ This project is a work in progress and is not ready for production use yet!

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.

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 run dev

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