Skip to content
Primer React components
Branch: master
Clone or download
Latest commit a42d5ea Jul 19, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Add TypeScript def check to merge checklist Jul 3, 2019
codemods add codemod Mar 13, 2019
pages Merge pull request #498 from primer/aria-label Jul 19, 2019
script change system-props to constants in prepack Dec 20, 2018
src Merge pull request #498 from primer/aria-label Jul 19, 2019
static/assets add new og image Dec 7, 2018
.babelrc switch to as Mar 12, 2019
.eslintrc.json don't warn on spread out variables Dec 18, 2018
.gitignore ignore tarballs in git Sep 7, 2018
.npmrc add git-tag-version=false to .npmrc Jul 30, 2018
.nvmrc add .nvmrc for Node>=8 May 21, 2018
CODE_OF_CONDUCT.md add Code of Conduct May 29, 2019
CONTRIBUTING.md Merge branch 'release-13.1.0' into upgrade-styled-system Jun 24, 2019
LICENSE Create LICENSE (#348) Nov 7, 2018
README.md Change CONTRIBUTING filename case May 27, 2019
css.js fix require path for dist/css Sep 26, 2018
index.d.ts update ts Jul 19, 2019
jest.config.js move jest config out of package.json Sep 7, 2018
migrating.md Add note about package name change in v3 Oct 16, 2018
next.config.js Load .css files as raw strings Jul 1, 2019
now.json add alias and scale back to now.json Oct 9, 2018
output.txt trigger deploy Mar 21, 2019
package-lock.json Merge pull request #488 from primer/link Jul 19, 2019
package.json Merge pull request #488 from primer/link Jul 19, 2019
prettier.config.js add prettier + eslint configs May 21, 2018
principles.md tweaks and typos Dec 7, 2018
rollup.config.js Use raw.macro instead of rollup-plugin-string Jul 18, 2019

README.md

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).
You can’t perform that action at this time.