GithubHelp home page GithubHelp logo

primer / react Goto Github PK

View Code? Open in Web Editor NEW
1.9K 26.0 292.0 57.43 MB

An implementation of GitHub's Primer Design System using React

Home Page:

License: MIT License

JavaScript 2.49% TypeScript 97.15% Shell 0.09% Ruby 0.27%
primer react component-library design-system

react's Introduction

Primer React

A React implementation of GitHub's Primer Design System


Our documentation site lives at You'll be able to find detailed documentation on getting started, all of the components, our theme, our principles, and more.


Install @primer/react in your project with your package manager of choice:

npm install @primer/react

// or

yarn add @primer/react


You can track our roadmap progress in the Roadmap Project Board, see more detail in the quarterly planning Discussions, and find a list of all the current epic tracking issues here.


We love collaborating with folks inside and outside of GitHub and welcome contributions!

👉 See the contributing docs for more info on code style, testing, coverage, and troubleshooting.

New Component Proposals

We welcome and encourage new component proposals from internal GitHub teams! Our best work comes from collaborating directly with the teams using Primer React Components in their projects. If you'd like to kick off a new component proposal, please submit an issue using the component proposal issue template and we will get in touch!

react's People


shawnbot avatar colebemis avatar BinaryMuse avatar T-Hugs avatar VanAnderson avatar smockle avatar jonrohan avatar siddharthkp avatar broccolini avatar dmarcey avatar dependabot[bot] avatar dgreif avatar mperrotti avatar jfuchs avatar primer-css avatar pksjce avatar github-actions[bot] avatar rezrah avatar mxstbr avatar keithamus avatar koddsson avatar dependabot-preview[bot] avatar HaigDouzy avatar mattcosta7 avatar albingroen avatar ashygee avatar iansan5653 avatar lffg avatar pavelkeyzik avatar jclem avatar


Alibaba Ahmed avatar Zach Gover avatar 0xMRTT avatar Salvydas Lukosius avatar Ou/Olly Kunanan Tassuwan avatar Sandr Klimenko avatar Luiz Eduardo avatar Jônatas Araújo avatar Yuri avatar Neil Zheng avatar Tyler Garner avatar  avatar Rajab Natshah avatar 혀느현스 avatar Caleb Russel Elat avatar Math W. avatar darker avatar Shreyasi Patil avatar Son Nguyen avatar Oktay avatar  avatar Ayush Saini avatar Dmitriy Malakhov avatar Yashwant Saini avatar Ash avatar Devansh Bajaj avatar Luiz Fernando da Silva Cieslak avatar Sangeeth Sivan avatar Gary Grumbley avatar Elena Bravo avatar Daniel avatar Buchanan Quantum avatar  avatar FW avatar alberto ventafridda avatar ashley avatar Shubham Ingale avatar Pedro Oliveira avatar Chenbae avatar  avatar Alex avatar toshito hirooka avatar  avatar He Linming avatar Naman Modani avatar Joe Gallegos avatar Ivan Spetter avatar Serenay USLU avatar Maxime  P avatar  avatar Pavel Erokhin avatar Ali H. Kudeir avatar Alexandros Ntitoras avatar Benjamin Bellamy avatar Oliver Barnwell avatar Chris Lonardo avatar Andrejus avatar NΛRCISO avatar 王树贤 avatar Alucard avatar William Chang avatar mrasong avatar Arunkumar R R avatar Oleg Lupanov avatar ycl avatar Makoto M avatar Andrey Smirnov avatar  avatar Vakhabow Shamil avatar Magomed Katalov avatar Rickvian Aldi avatar Hebert  F. Barros avatar Зелим avatar Eric Wong avatar  avatar xyz avatar Vitaliy Irtlach avatar Trust Onyemachi avatar Matthew Francis Brunetti avatar Murad Khalimov avatar  avatar Jonatan Frederico avatar Tejas Sawant avatar  avatar DT avatar 深樹 avatar Minh avatar 小傅Fox avatar Jianan Sun avatar Zixuan Tang avatar Windfarer avatar Wang Guan avatar lazzzis avatar  avatar Janlay avatar Himself65 avatar Michael Chiche avatar Sonja Feitsch avatar Niketan Gulekar avatar Kim do gon avatar


Jonathan Fuchs avatar Michelle Tilley avatar Diana Mounter avatar Jeff Wilcox avatar Hubot avatar James Cloos avatar Josep Martins avatar Rajab Natshah avatar Tony Brown avatar Mike Perrotti avatar Go7hic avatar Leslie Cohn-Wein avatar Cole Bemis avatar Jigyasu Arya avatar Wellington Torrejais da Silva avatar Arturo Romero avatar emplums avatar bing avatar Alexis Lucio avatar Moc Thanh An avatar Kevin Bush avatar  avatar  avatar  avatar  avatar  avatar

react's Issues

Kit updates


  • PropsForms
  • Top navigation & separate Library components for presentational & demo components
  • v1 Sandbox
  • Primer styles for sidebars and top nav
  • Fix HMR

Whitelisting certain props?

This week's work has given us an opportunity to mull over whether components should be "strict" in which props they allow users to pass — or, as an implementation detail, which ones they actually respect. I can think of a couple that we may want to whitelist for some, if not all, Primer components:

  1. id could people to provide deep links without having to wrap another element around their content.
  2. hidden would provide a more systematic way to show and hide things.
  3. Any aria- attribute, because a11y.
  4. Any data- attribute, to provide hooks for JS behaviors implemented by container components.


Make `shadow` prop only accept string values

Ref: #70 (comment)

What do you think about changing the shadow API here to accept small, medium, large, extra-large and then instead of accepting either a boolean or a string we can just accept strings and this line would be

shadow && ((shadow === 'small') ? 'box-shadow' : `box-shadow-${shadow}`)

Document how to import custom Primer CSS

We need some "official" way to import Primer CSS. Here's how we've done it in our docs site:

  1. At first, we just linked out to a bunch of URLs. This is okay for demos and sandboxes, but not good for production.
  2. In #238, I set up the Next sass plugin to output a static CSS file as part of the webpack build. This is okay too, but we need to address other use cases.

Build "full" UMD bundle?

Our UMD build doesn't currently bundle any of the external dependencies, including d3-shape or Octicons. If we want to support CodePen and other, dependency-unaware environments, we'll need to build a browser-ready UMD bundle with all the batteries included.

Do we need individual packages or not?

In primer/primer we have a separate package for each component or group of styles. We set it up like this so that people could only pull in the styles they need so as to avoid unnecessary bloat. Do we need to do this with React components? We don't have quite the same concerns with CSS bloat. I do think we will still have some distinction between dotcom and marketing sites, so perhaps there is an "addons" package, but otherwise maybe we don't need to break it up quite as much. Let me know what you think!

cc @primer/ds-core

Public Beta Checklist

Items that need to be completed before our first public beta


  • Support documentation for components in markdown format
  • Point site to
  • Default theme for each component?
  • "Good enough" test coverage
  • Index page design
  • Every component documented
    • Simple (default) example
    • Component Props
    • Basic implementation guidelines
  • System props documented
  • Installation guidelines, aka "how to use in your app"
    • confirm what packages are needed
  • Component(s) to import Primer CSS #124
  • Rename the repo to primer/components
  • Scope on npm


  • Shipped


  • Improved doc design #231
  • A way to provide feedback


  • Copy over usage guidelines from style guide
  • Add favicon


  • Remaining Primer CSS components #100
  • Provide docs for how to use your own theme
  • Ship dev mode

Caret API improvements

The Caret component introduced in #58 has some issues that I'd like to address:

  • The combination of edge and align props is kind of confusing, and the align prop is currently ignored. I think that a location prop with values like top, top-left, etc. will be more intuitive, and matches the Popover position naming conventions.
  • As discussed with @jonrohan, it's probably safe to kill off the hacky CSS implementation and just use SVG.
  • It's currently a pain to coordinate the border and background colors between a Box and Caret, so I'd like to introduce a component that combines them. Possible names include: BoxWithCaret, PointyBox, CaretBox, and CarrotBox... :trollface:

We should take this opportunity to address the positioning inconsistencies with Popover, and possibly even re-implement Popover as a Box + Caret!

Remaining Docs fixes

  • Currently on the static site the top level nav goes to urls like this /primer-react/docs/[page], but clicking on components in the component library changes the url to /docs/[page]/[component]. This is due to a difference between how routing is working locally vs on the static site. Locally, /primer-react is not prefixed to every url (because GH pages is doing that), so in order for HMR to work, the routes need to go to /docs/page/component instead of /primer-react/docs/page/component. Fun times 🙃

  • The url generated by gh pages is /primer-react, but the static site actually lives at /primer-react/docs

Updates to merge box

  • fix pending state
  • rethink API around data structure
  • create a demo container component

Should fontSize go up or down?

@emplums asked a good question here:

[...] we are inverting the fontSize scale here?

When @broccolini started this repo, fontSize was translated directly to CSS font-size in a styled component. So my goal was to have a prop that mapped increasing numbers to increasing sizes, which is the inverse of our f? classes. 😱 I have no idea which is "right", though, so let's discuss!

Publish docs automatically

Currently our process of running npm run build to update the docs directory (so that we can then publish to GitHub Pages) is a bit tedious and error-prone because:

  1. It inevitably causes merge conflicts
  2. It's a manual step that I often forget to run before pushing
  3. It won't happen automatically when we merge branches

I propose that we build the site on CI (which also ensures that the site always builds) and publish it from there, ideally to a branch-specific URL on the gh-pages branch so that the URL would be, for instance,

Make Primer Sass-only version

I think it makes sense to fork this repo and make a version of react components that uses existing Primer styles only. That allows us to explore how we break down components while we test out CSS-in-JS solution which will take longer to build.

Utility class mapping

I've been using the Primer mapping from system-classnames in #32, but after looking into Text and Heading components I think we should consider more granular mappings for each, e.g.

import createMapper from 'system-classnames'

const breakpoints = [null, 'sm', 'md', 'lg', 'xl']
// one day? import {breakpoints} from 'primer-primitives'

const createPrimerMapper = props => createMapper({
  getter: ({breakpoint, prop, value}) => breakpoint
    ? [prop, breakpoint, value].join('-')
    : [prop, value].join('-')

const textMap = createPrimerMapper(['h', 'f', 'lh', 'text'])
const boxMap = createPrimerMapper([
  'bg', 'text', 'border', 'rounded', 'box-shadow',
  'position', 'top', 'right', 'bottom', 'left',
  'v-align', 'overflow', /* 'float', */
  'width', 'height', 'min-width' // these might need to be handled separately

export default createPrimerMapper
export {textMap, boxMap}

Then Box, Text, and Heading would each use them like:

const Box = props => <div {...boxMap(props)} />
const Text = props => <span {...textMap(props)} />
const Heading = props => <h1 {...textMap(props)} />
Heading.h2 = props => <h2 {...textMap(props)} />
// etc.

Does this seem like the right way to go about it?

prop to describe color theme

We need to come up with a name for a prop that describes a color theme (background color + text color, etc)... theme could easily be mixed up with our themes (light/dark). Maybe colorPattern? colorScheme ? maybe theme is ok? thoughts?

Discussion: Autofocus on TextInput component

@shawnbot noticed that the TextInput component include an autofocus prop + attribute. I'm curious if there's a strong use case for needing this here, or if it would be ok to remove it? The reason being that autofocus can have negative a11y consequences as it disorients screen reader users without warning. From MDN:

Warning: Automatically focusing a form control can confuse visually-impaired people who using screen-reading technology. When autofocus is assigned, screen-readers "teleport" their user to the form control without warning them beforehand.

Additionally, only one element per page should have the autofocus attribute and we currently don't have any way of enforcing that.

Curious if there is a strong reason why we decided to add it? cc @jonrohan @shawnbot @broccolini

Extend a component

Extend a component (such as buttons) to provide an example of how we'll approach this with any component, such as when do you extend vs add props.

fontSize in Text

The fontSize prop in Text goes from 0-6 and maps them backwards to match up to the primer/primer scale which goes from 6-0. Let's create 1:1 with primer/primer and keep the scale going from 6-0

The release build doesn't include the dist directory

You can't import the latest version of primer-react because the published package doesn't include the dist/ directory. This is because I put the build step in our preversion run-script instead of prepublishOnly, and since we're not versioning on Travis it never ran. So yeah, I need to fix that. 🤦‍♂️

Sharing system utility props across components & component types

I did some testing using primer-react in a project this weekend, and I found some things too inflexible in places that will make it too hard to work with and might cause us some headaches too. I think I'd rather be a little more flexible than constrain stuff too much. Here's some suggestions:

  • Everything should have space (margin/padding) and color (color/bg) utility props
  • Add a CSS prop for applying one-off css styles to any component like this

I think we can group components in categories to help us make the same utility props available, this will make them easier to compose with, and create some standardization across components:

  • Text styles:
    • Props: fontSize, lineHeight
    • Components: Text, Heading, Link, Label, Counter, State Tooltip, Button, Form elements
  • Layout:
    • Props: width (such as width={[1,2/3, 1/2]} mapping to our col-width utilities), container (such as container-lg) (same as breakpoints), border
      • Block (Box), Flex
  • Interactive:
    • Props: onClick handlers
      • Forms, Buttons

Some other areas that need more thought:

  • "Polish", such as box shadows, border-clip etc. - perhaps should be utility props?
  • How should we handle position? Component or props or both?

cc @primer/ds-core

Example permalinks don't work

Our x0-driven docs site doesn't generate working component permalinks. When we publish to Pages, the index loads from /primer-react/, but the links all go to /{ComponentName} (without the right path prefix). The pages for individual components don't even really exist (there's only an index.html in the docs directory), so I'm not sure what the URLs really should be for a component example. Having working permalinks seems pretty crucial to me.

To reproduce, visit and click on "Details". The URL changes to, which doesn't exist. But neither do any of the following:


We've already set x0.basename in package.json as described in x0's docs, but the URLs that are getting passed to location.replace() or history.pushState() just aren't right.

Any ideas, @broccolini?

Refactor `border` prop

From @emplums in this review:

This is maybe one for another PR, but what do you think about separating the border utilities into two different props? We could have border and borderColor? I think that would make reasoning with the prop a bit more intuitive on the user side & would make it easier to create classes here! It looks like the styleguide docs also encourage using two separate classes for border/border-top/etc and border color utilities

Also curious if we need to allow people to pass in border={0}, and we instead make the Block component have no border by default?

I agree 100%!

UnderlineNav follow up items

🐛 Bugs

  • Underline is red-orange when Kit is first loaded, but once you navigate to other tabs, it turns grey.

🚀 Enhancements

  • Spread children's props back onto cloned child
  • Move rendersClass into utility file
  • Consider whether or not it's ok to have a circular dependency between UnderlineNav and UnderlineNavLink

Flexbox component

Needs to include API for:

  • flex or inline flex option
  • flex direction
  • flex wrap
  • justify content
  • align items
  • align content
  • flex-auto
  • align self
  • responsive flex utilties

Make a composit component

To act as a template for other composit components. I.e. show how we handle spacing and styling components within a component etc.

Clean up the donuts

  1. This line is a mess: child.props.key doesn't exist, which results in un-keyed elements. Maybe calling React.cloneElement() would be better here?
  2. The DonutPropType bit is kind of silly. That PropTypes.shape() call can be wrapped in oneOrMoreOf() from props.js.

Primer-react v1 beta - release tracking

Tracking v0.0.1-beta




  • Flex component
  • Tooltip component

Composite Component: Merge Box

This is a tracking issue to detail all the components we need to recreate the merge box.

  • Avatars
  • Dropdown
  • Hide/show details toggle
  • Dismiss review form
  • Branch name
  • This graph thing
  • Status icon
  • Tooltip

Add Details component

We need Primer-specific <details> + <summary> components for #45 (and #43):

"Show/hide all checks" link

This one is a slightly more complicated version of a native <details>, in that it needs to show different text depending on when it's open or closed.


In this one, the "pressed" state of the arrow changes when you open and close it, and the dropdown content is absolutely positioned. The tricky thing here is using <details> and <summary>, because they require that the latter is nested directly in the former.

I've whipped up an example of how we could do this using the render props pattern, which makes the open and toggle props available to children so that the author can decide what's visible and hidden in the summary without managing state.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.