GithubHelp home page GithubHelp logo

primer / react Goto Github PK

View Code? Open in 1sVSCode Editor NEW
1.7K 22.0 257.0 52.71 MB

An implementation of GitHub's Primer Design System using React

Home Page:

License: MIT License

JavaScript 3.03% TypeScript 96.52% Shell 0.11% Ruby 0.34%
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 broccolini avatar siddharthkp avatar dmarcey avatar dependabot[bot] avatar dgreif avatar jfuchs avatar mperrotti avatar primer-css avatar pksjce avatar github-actions[bot] avatar rezrah avatar mxstbr avatar keithamus avatar koddsson avatar dependabot-preview[bot] avatar HaigDouzy avatar albingroen avatar ashygee avatar lffg avatar pavelkeyzik avatar acknosyn avatar jclem avatar alanbsmith avatar


Josias Aurel avatar Umang Bhalla avatar John D. Jameson avatar harshavardhanpb avatar Jason Jun avatar Andrew Eisenberg avatar Elvin Garcia avatar Tarek Hammami avatar Josh Bowden avatar  avatar  avatar 骗你是小猫咪 avatar Arman Zhumanov avatar Ryu Hyun Seung avatar Juho Niinikoski avatar John S. Dvorak avatar Ram Murmu avatar nkot56297 avatar Aleksei Saenko avatar  avatar Niag de Souza Alves avatar Paul Ccari avatar Xinhe avatar Eric Bailey avatar  avatar Degreat avatar Connor Baker avatar Ininit avatar Lin-PQ avatar GabrielFox.Dev avatar Kornel Dubieniecki avatar kyesu avatar Fabian Lee avatar Chris Springer avatar PawelKonarzewski avatar  avatar NEO LI avatar Guilherme Fernandes avatar Niklas Marion avatar Alan Gabriel avatar Adebayo Ilerioluwa  avatar Thomas Hartwig avatar  avatar James Restall avatar Juan Andrade avatar Jack Sullivan avatar 50岁的星空 avatar free_one_ avatar Second Datke avatar SilverPrize avatar Aritra Sen avatar Parker Brown avatar Thays Giotto avatar Aditya Bhagat avatar Prodip_7 avatar Bijoy Das avatar Vishal Kothari avatar Леон avatar  avatar とちざわ avatar Dishant Kamble avatar Benrandja Akram avatar Ramazan Erikli avatar  avatar Florin Cotovanu avatar Adam Braimbridge avatar Robert Cecil William'JR Hamilton  avatar  avatar Robert Niznik avatar  avatar HuaDream avatar yu avatar Mariah avatar Harshad Ranganathan avatar Don avatar Mark avatar  avatar vical avatar Sachith avatar MikeKen avatar Sunghoon Kang avatar  avatar  avatar Nityam avatar William avatar Jitendra Nirnejak avatar Shekar Siri avatar Danny Englander avatar  avatar zhixuan avatar Takeshi avatar Runzhou Li (Leo) avatar MERT avatar Tuan Duc Design avatar Daniel avatar  avatar WellPower avatar Khánh Hoàng avatar  avatar Andrew Moss avatar


Jonathan Fuchs avatar Michelle Tilley avatar Diana Mounter avatar Jeff Wilcox avatar Hubot avatar James Cloos avatar Tony Brown avatar Simon Taranto avatar Mike Perrotti avatar Go7hic avatar Cole Bemis avatar Jigyasu Arya avatar Wellington Torrejais da Silva avatar Arturo Romero avatar emplums avatar bing avatar Kevin Bush avatar  avatar  avatar  avatar  avatar  avatar

react's Issues

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.

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.

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?

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.


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

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!

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

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%!

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,

Kit updates


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

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.

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

Primer-react v1 beta - release tracking

Tracking v0.0.1-beta




  • Flex component
  • Tooltip component

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.

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.

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?

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?

Updates to merge box

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

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

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.

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}`)

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. 🤦‍♂️

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

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

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

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

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!

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

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.

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.