Skip to content

Latest commit

 

History

History
130 lines (92 loc) · 4.33 KB

README.md

File metadata and controls

130 lines (92 loc) · 4.33 KB
Raw

Primer react

Primer React components

Status

⚠️ This project is WIP and not ready for production use yet!

Currently we link to the latest build of Primer CSS so that we may use current Primer styles to start to build components. This does not include primer-base so as to avoid unwanted base overrides.

Installation

Install @primer/components in your project with npm:

npm install @primer/components

Usage

If you are upgrading from a version before 1.0.0-beta, please read the migration docs.

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'

Styling

This project uses emotion to generate static CSS for most component styles, but still relies on Primer CSS for some classname-based styles that haven't yet been ported over.

To ensure proper styling of all Primer components, you'll need to include some static CSS that's distributed with the @primer/components npm package in dist/primer-components.css.

JavaScript bundlers

If you're using a JavaScript bundler that supports CSS imports, you can import it in your bundles directly:

import '@primer/components/dist/css/build.css'

If you're using webpack, you will need to install style-loader and configure webpack to use it for imports ending in '.css', e.g.

{
  module: {
    rules: [
      {
        test: /\.css$/,
        use: 'style-loader'
      }
    ]
  }
}

Server inlining

If you run a Node server, you can read the file from disk at startup:

const {readFileSync} = require('fs')
const cssPath = require.resolve('@primer/components/dist/primer-components.css')
const css = readFileSync(cssPath, 'utf8')

Then, inline it into the <head> of your HTML template(s) or render it server-side in React like so:

// assuming the `css` variable is set as above
export default () => (
  <html>
    <head>
      <style>{css}</style>
    </head>
    <body>
      ...
    </body>
  </html>
)

Static apps

For fully static or statically generated (Jekyll, Hugo, etc.) apps, you may need to manually copy node_modules/@primer/components/dist/css/build.css (after npm install --save @primer/components) to one of your site's public directories, i.e. /assets:

cp node_modules/@primer/components/dist/css/build.css assets/primer-components.css

Then link to it in the <head> of your HTML document(s):

<link rel="stylesheet" href="/assets/primer-components.css">

Static CSS rendering

Some Primer components rendered client-side may produce a flash of unstyled content. You can avoid most jarring flashes by ensuring that primer-components.css is either inlined or linked in the <head> of your document with one of the techniques described above.

If you're rendering React components both server-side and client-side, we suggest following Emotion'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).