loading...
React components for the Primer Design System
Install @primer/components in your project with npm:
npm install @primer/components
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.
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 to style <body> in Primer CSS.
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.
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.
To run @primer/components locally when adding or updating components:
git clone https://github.com/primer/componentsnpm installnpm start👉 See the contributing docs for more info on code style, testing, and coverage.