React components for the Primer Design System
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.
Install @primer/components in your project with your package manager of choice:
npm install @primer/components // or yarn add @primer/components
All of our components are exported by name from
@primer/components, so you can import them with:
Primer Components come with all the necessary CSS built-in, so you don't need to worry about including Primer CSS.
You can establish base Primer styles for your app by wrapping all of your Primer components in
import BaseStyles Box Heading from '@primer/components'<BaseStyles><Box =><Heading =>Hello world!</Heading><p>This will get Primer text styles</p></Box></BaseStyles>
This will set the
line-height CSS properties to the same ones used in primer-base.
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 = propsreturn<div><ThemeProvider =><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 = propsreturn<div><ThemeProvider => // 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.
@primer/components locally when adding or updating components:
- Clone this repo:
git clone https://github.com/primer/components
- Install dependencies in the repo root and
pushd docs && yarn && popd && yarn
- Run the dev app:
👉 See the contributing docs for more info on code style, testing, coverage, and troubleshooting.
- 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).