Détail du package

@primer/components

primer6.2kMITobsolète33.1.0

@primer/components has been renamed @primer/react. Use @primer/react instead.

Primer react components

react, components, library, design-system

readme

Primer React

A React implementation of GitHub's Primer Design System

Documentation

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

Installation

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

npm install @primer/components

// or

yarn add @primer/components

Roadmap

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.

Contributing

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!

changelog

@primer/components

33.1.0

Minor Changes

Patch Changes

33.0.0

Major Changes

Minor Changes

Patch Changes

  • #1668 98dc6336 Thanks @siddharthkp! - ActionList: Fix multiple selection svg by overriding global shape-rendering for github.com

  • #1596 5c6dc644 Thanks @dmarcey! - Fix alignment of items in ActionList (single-select) if some of the items have wrapping text.

  • #1538 dda6e5d7 Thanks @shiftkey! - Update typescript package to correct generated type declarations.

32.1.0

Minor Changes

Patch Changes

  • #1648 8b40a0a9 Thanks @jfuchs! - Fixed a bug with Overlay's type where DOM props were not allowed.

32.0.1

Patch Changes

32.0.0

Major Changes

Patch Changes

31.2.0

Minor Changes

  • #1544 5b55b0ab Thanks @jfuchs! - The sx prop now has types that will inform autocomplete for color and shadow values that are key paths into the theme.

  • #1517 561c0bd3 Thanks @siddharthkp! - Add experimental ActionList with composable API

Patch Changes

31.1.0

Minor Changes

  • #1523 56e2f159 Thanks @mperrotti! - Add the ability to truncate tokens in the TextInputWithToken component when the input is not focused

Patch Changes

  • #1529 da566044 Thanks @mperrotti! - Fixes a bug in TextInputWithTokens where the next token would not receive focus after the user deleted the first token using the keyboard

  • #1526 1378e771 Thanks @mperrotti! - replaces flexbox gap usage with margins

31.0.1

Patch Changes

  • #1521 28b5980c Thanks @siddharthkp! - Add trailingVisual prop to ActionList/ActionMenu. Deprecate trailingIcon and trailingText props.

31.0.0

Major Changes

Patch Changes

30.3.0

Minor Changes

30.2.1

Patch Changes

30.2.0

Minor Changes

  • #1497 b9d6a662 Thanks @jfuchs! - Updated ActionList's ItemInput type to accept DOM props for divs when renderItem is not provided

30.1.0

Minor Changes

  • #1463 bde3a034 Thanks @jfuchs! - ActionList.item accepts an as prop, allowing it to be a link, or (in combination with the renderItem prop) a Next.js or React Router link

Patch Changes

  • #1471 f1cebb7e Thanks @smockle! - Change the button which receives focus when a 'ConfirmationDialog' opens from the secondary (e.g. 'Cancel') to the primary (e.g. 'OK'). Fixes github/primer#313.

30.0.0

Major Changes

  • #1448 1a39fb02 Thanks @SferaDev! - Remove .Breadcrumb classname from the root element of the Breadcrumbs component. This change shouldn't break anything unless you have styles, scripts, or tests that reference the .Breadcrumb classname.

  • #1468 dc15763c Thanks @jfuchs! - AvatarStack no longer accepts styled props or DOM props

Minor Changes

Patch Changes

29.1.1

Patch Changes

  • #1441 f3f5afb9 Thanks @jfuchs! - Fix type error where css is a required prop of some components by excluding storybook stories from TypeScript compilation for builds

  • #1446 b4e5287c Thanks @colebemis! - Fix filter input spacing in SelectPanel

29.1.0

Minor Changes

29.0.0

Major Changes

  • #1414 f4e1de6d Thanks @jfuchs! - Removed system props support from <TextInput> and fixed its type definition.

Minor Changes

Patch Changes

28.5.0

Minor Changes

  • #1398 e4dac575 Thanks @jfuchs! - Default portal containers created by primer are absolutely positioned at 0,0

  • #1385 5470b61b Thanks @jfuchs! - Make top and left position explicit props of Overlay handled separately from other styles

  • #1388 83b888f0 Thanks @jfuchs! - Overlay takes a portalContainerName prop. This allows overlays with an anchor inside a scrolling container to track with their anchor, so long as the specified portal is also inside that scrolling container.

28.4.0

Minor Changes

Patch Changes

  • #1372 23be0ed7 Thanks @jfuchs! - Extends DropdownMenu to allow anchorRef, open, and onOpenChange props.

  • #1386 2ea30b43 Thanks @colebemis! - Bump @primer/primitives dependency to 4.6.4

  • #1387 6b4d52da Thanks @jfuchs! - Guard against MediaQueryList.addEventListener calls where unavailable and possibly fall back to .addListener

28.3.2

Patch Changes

  • #1368 36f156a0 Thanks @dgreif! - Allow anchorRef to be passed into SelectPanel if you want to use an external anchor

28.3.1

Patch Changes

28.3.0

Minor Changes

  • #1315 85d0202b Thanks @VanAnderson! - Box now accepts all styled system props.

  • #1316 4c063317 Thanks @VanAnderson! - The following components have been deprecated in favor of the Box component:

    | Component | Replacement | | ----------- | ------------------------------------------------------------------------------------------- | | Flex | <Box display="flex"> | | Grid | <Box display="grid"> | | Position | <Box> | | Absolute | <Box position="absolute"> | | Fixed | <Box position="fixed"> | | Relative | <Box position="relative"> | | Sticky | <Box position="sticky"> | | BorderBox | <Box borderWidth="1px" borderStyle="solid" borderColor="border.primary" borderRadius={2}> |

    There is a codemod available to upgrade these components:

    • TypeScript example:

      npx jscodeshift -t node_modules/@primer/react/codemods/deprecateUtilityComponents.js
--parser=tsx path/to/workspace/src/*.tsx

    • Babel example:

      npx jscodeshift -t node_modules/@primer/react/codemods/deprecateUtilityComponents.js
--parser=babel path/to/workspace/src/*.tsx

  • #1336 489a718b Thanks @VanAnderson! - System props are deprecated in all components except Box. Move all system props into the sx prop instead. Example:

    - <Button mr={2}>...</Button>
+ <Button sx={{mr: 2}}>...</Button>

    There is a codemod available to migrate from system props to the sx prop:

    • TypeScript example:

      npx jscodeshift -t node_modules/@primer/react/codemods/removeSystemProps.js
--parser=tsx path/to/workspace/src/*.tsx

    • Babel example:

      npx jscodeshift -t node_modules/@primer/react/codemods/removeSystemProps.js
--parser=babel path/to/workspace/src/*.tsx

Patch Changes

  • #1332 ec11d7b8 Thanks @mattcosta7! - Side effects are properly declared in package.json

  • #1308 a8f3ca6d Thanks @dgreif! - Focus zones will now update active-descendant on mousemove over focusable elements. ActionList has been updated to handle direct (key press) vs indirect (mousemove, DOM change, etc.) changes to active-descendant, and will use a distinct background color for the directly activated items.

28.2.5

Patch Changes

  • #1311 6f0535df Thanks @lukewar! - Expose 'textInputProps' from the 'SelectPanel'

  • #1309 dc17a49e Thanks @colebemis! - Include all shadow variables in theme object

  • #1251 528e9a41 Thanks @VanAnderson! - Call useOnOutsideClick handlers in reverse order that they are registered, and allow propagation to stop if default is prevented or an non-outside click is detected.

  • #1312 76a38432 Thanks @smockle! - Ensure clicking an AnchoredOverlay’s trigger allows it to close without immediately reopening.

28.2.4

Patch Changes

  • #1293 1148a718 Thanks @smockle! - Restore "fix: Don’t focus first 'Item' of 'DropdownMenu' and 'SelectMenu' on open" by deferring the removal of a temporary tabIndex until focus moves within the container.

  • #1279 bb38754f Thanks @VanAnderson! - Update overlay shadows

  • #1297 5fb3683d Thanks @VanAnderson! - Bump @primer/primitives to 4.4.0

  • #1288 15207119 Thanks @dgreif! - Focus zones with an activeDescendantControl will now activate the first descendant as soon as the control element is focused, rather than waiting for an up/down arrow press. Descendants stay active until the control element is blurred. This is a breaking change to useFocusZone, but this behavior is still considered to be in alpha.

  • #1292 4b643818 Thanks @dgreif! - Bump dependencies

  • #1279 bb38754f Thanks @VanAnderson! - Update TextInput border color

28.2.3

Patch Changes

28.2.2

Patch Changes

28.2.1

Patch Changes

28.2.0

Minor Changes

  • 8368a83e #1238 Thanks @dgreif! - New sizes for Overlay and Dialog. Sizes have been changed from abbreviations to full words. xs -> xsmall, sm -> small, md -> medium, lg -> large, xl -> xlarge. The sizing for Overlay has also been updated to provide a wider range of options. The original values for Overlay were based on the needs of Dialog, but Dialog is not reliant on Overlay so they don't need to have similar sizing. This is technically a breaking change, but is being released as a minor because these components are both still in alpha status.

Patch Changes

28.1.1

Patch Changes

28.1.0

Minor Changes

Patch Changes

28.0.4

Patch Changes

28.0.3

Patch Changes

  • c63fa4b5 #1215 Thanks @dgreif! - Hide divider before ActionList.Groups with filled header

  • a9260812 #1221 Thanks @dgreif! - Improved performance for lists in ActionMenu and DropdownMenu

  • c63fa4b5 #1215 Thanks @dgreif! - Align Item description to when rendered in-line

  • c63fa4b5 #1215 Thanks @dgreif! - Allow focusZoneSettings to be passed into AnchoredOverlay

  • c63fa4b5 #1215 Thanks @dgreif! - Add selectionVariant: 'multiple' for Items. These will use a checkbox input instead of a checkmark icon for selected state

  • d78af591 #1214 Thanks @VanAnderson! - renderMenuItem in ActionMenu checks preventDefault for conditionally calling onClose

  • 4ab3d175 #1222 Thanks @dgreif! - Trap focus in AnchoredOverlay as soon as it opens, regardless of the event that triggered it to open

  • ff9ce6f1 #1217 Thanks @VanAnderson! - overlayProps passthrough from ActionMenu and DropdownMenu to AnchoredOverlay.

28.0.2

Patch Changes

  • d20a5996 #1209 Thanks @dgreif! - Allow Overlay height and width to be set through AnchoredOverlay Allow ActionList Items to supply an id instead of key Performance imporvements when ActionList is not given any groups Enable focus zone as soon as AnchoredOverlay opens

  • d29741ca #1196 Thanks @dgreif! - Allow custom children in ActionItem. text and description can still be provided as a shortcut, but children is now available if you need more control over the rending of the item, without sacrificing benefits from Item by using renderItem.

  • 4c2e1a2b #1195 Thanks @VanAnderson! - Export useConfirm hook and ConfirmationDialog component from index.

  • 3c13d039 #1201 Thanks @T-Hugs! - Fix overlay position when using an AnchoredOverlay

  • c9b4db79 #1199 Thanks @VanAnderson! - Action Menu can have its open state be controlled externally.

  • 3e759e59 #1211 Thanks @VanAnderson! - Use preventDefault on AnchoredOverlay instead of stopPropagation.

  • 84e3c570 #1194 Thanks @dgreif! - Handle onAction for DropdownMenu Items

  • 7aeb53fe #1200 Thanks @dgreif! - Perform ActionMenu actions after overlay has closed. This allows the action to move focus if so desired, without the ActionMenu focus trap preventing focus from moving away.

  • bba66fdd #1206 Thanks @VanAnderson! - stopPropagation for mousedown and click in AnchoredOverlay based components

28.0.1

Patch Changes

28.0.0

Major Changes

  • 5f85394d #1157 Thanks @dgreif! - Removed useMouseIntent in favor of :focus-visible. With the removal of useMouseIntent, the intent-mouse class will no longer be added to the <body>. Since :focus-visible is a relatively new psuedo-class, a polyfill is included. Any focused elements that meet the criteria for :focus-visible will also have a focus-visible class added to them by the polyfill.

Patch Changes

27.0.0

Major Changes

  • db478205 #1147 Thanks @colebemis! - Type definitions are now being generated by TypeScript instead of manually maintained. These new type definitions may differ from the previous type definitions and cause breaking changes. If you experience any new TypeScript errors, feel free to create an issue or reach out in Slack (#design-systems).

    Breaking changes

    • The following types are no longer exported:

      BaseProps
UseDetailsProps
AnchoredPositionHookSettings
AnchorAlignment
AnchorSide
PositionSettings
PaginationHrefBuilder
PaginationPageChangeCallback
PositionComponentProps

    • Props are now defined with types instead of interfaces which means in some cases you may not be able to create interfaces that extend them. To work around this issue, you may need to convert your interfaces to types:

      import {BoxProps} from '@primer/react'

- interface MyFancyBox extends BoxProps {...}
+ type MyFancyBox = BoxProps & {...}

    • Some components now expect more specific ref types. For example:

      - const ref = React.useRef<HTMLElement>(null)
+ const ref = React.useRef<HTMLButtonElement>(null)

return <Button ref={ref}>...</Button>

26.0.0

Major Changes

  • 016a273f #1115 Thanks @VanAnderson! - Removes deprecated presentational theme variables in favor of functional variables for styling components that are consistent across multiple themes.

    Migration guide

    If you don't use any color-related system props (e.g. color, bg, borderColor), all components should work without changes. If you're using color-related system props, you'll need to update them to use the new functional variables. Reference the tables below to see how old variables map to new functional variables.

    If you have any questions, feel free to reach out in the #design-systems channel.

    Text

    | v25 | v26 | | ------------------------ | ------------------------ | | color="text.gray" | color="text.secondary" | | color="text.grayLight" | color="text.tertiary" | | color="text.grayDark" | color="text.primary" | | color="text.red" | color="text.danger" | | color="text.white" | color="text.inverse" | | color="gray.6" | color="text.secondary" | | color="gray.5" | color="text.tertiary" | | color="gray.9" | color="text.primary" | | color="red.6" | color="text.danger" | | color="white" | color="text.inverse" | | color="blue.5" | color="text.link" | | color="gray.4" | color="text.disabled" | | color="green.5" | color="text.success" | | color="yellow.8" | color="text.warning" |

    Icon

    | v25 | v25 | | ------------------ | ------------------------ | | color="gray.9" | color="icon.primary" | | color="gray.6" | color="icon.secondary" | | color="gray.4" | color="icon.tertiary" | | color="blue.5" | color="icon.info" | | color="red.5" | color="icon.danger" | | color="green.6" | color="icon.success" | | color="yellow.8" | color="icon.warning" |

    Border

    | v25 | v26 | | --------------------------------- | ------------------------------- | | borderColor="border.blue" | borderColor="border.info" | | borderColor="border.blueLight" | n/a | | borderColor="border.grayLight" | borderColor="border.primary" | | borderColor="border.grayDark" | borderColor="border.tertiary" | | borderColor="border.grayDarker" | n/a | | borderColor="border.green" | borderColor="border.success" | | borderColor="border.greenLight" | n/a | | borderColor="border.purple" | n/a | | borderColor="border.red" | borderColor="border.danger" | | borderColor="border.redLight" | n/a | | borderColor="border.white" | borderColor="border.inverse" | | borderColor="border.whiteFace" | n/a | | borderColor="border.yellow" | borderColor="border.warning" | | borderColor="border.blackFade" | borderColor="fade.fg15" | | borderColor="border.whiteFade" | borderCOlor="fade.white15" | | borderColor="blue.5" | borderColor="border.info" | | borderColor="gray.2" | borderColor="border.primary" | | borderColor="gray.3" | borderColor="border.tertiary" | | borderColor="green.4" | borderColor="border.success" | | borderColor="red.5" | borderColor="border.danger" | | borderColor="white" | borderColor="border.inverse" |

    Background

    | v25 | v26 | | ------------------- | ------------------------ | | bg="white" | bg="bg.primary" | | bg="bg.grayLight" | bg="bg.secondary" | | bg="bg.gray" | bg="bg.tertiary" | | bg="bg.grayDark" | bg="bg.canvasInverse" | | bg="blue.0" | bg="bg.info" | | bg="blue.5" | bg="bg.infoInverse" | | bg="red.0" | bg="bg.danger" | | bg="red.5" | bg="bg.dangerInverse" | | bg="green.1" | bg="bg.success" | | bg="green.5" | bg="bg.successInverse" |

    Labels

    Note the change in pluralization from 'labels' to 'label'.

    | v25 | v26 | | ----------------------------- | ------------------------------------- | | color="labels.grayDarkText" | color="label.primary.text | | borderColor="labels.gray" | borderColor="label.primary.border | | color="labels.grayText" | color="label.secondary.text | | borderColor="labels.gray" | borderColor="label.secondary.border | | color="labels.blueText" | color="label.info.text | | borderColor="labels.blue" | borderColor="label.info.border | | color="labels.greenText" | color="label.success.text | | borderColor="labels.green" | borderColor="label.success.border | | color="labels.yellowText" | color="label.warning.text | | borderColor="labels.yellow" | borderColor="label.warning.border | | color="labels.redText" | color="label.danger.text | | borderColor="labels.red" | borderColor="label.danger.border | | color="labels.orangeText" | color="label.primary.text | | borderColor="labels.orange" | borderColor="label.primary.text | | color="labels.pinkText" | n/a | | borderColor="labels.pink" | n/a | | color="labels.purpleText" | n/a | | borderColor="labels.purple" | n/a |

    Counters

    | v25 | v26 | | --------------------- | -------------------- | | scheme="gray" | scheme="primary" | | scheme="gray-light" | scheme="secondary" |

    Timeline

    | v25 | v26 | | ----------------------------------------- | ----------------------------- | | bg="red.5" | bg="prState.closed.bg" | | bg="green.5" | bg="prState.open.bg" | | bg="purple.5" | bg="prState.merged.bg" | | bg="gray.5" | bg="prState.draft.bg" | | color="white" (context: closed PR icon) | color="prState.closed.text" | | color="white" (context: open PR icon) | color="prState.open.text" | | color="white" (context: merged PR icon) | color="prState.merged.text" | | color="white" (context: merged PR icon) | color="prState.draft.text" |

25.0.0

Major Changes

  • 8799f74a #1112 Thanks @colebemis! - Primer React now supports color modes! 🎉

    See the new Theming documentation for more details.

    Breaking changes

    • You'll need to replace the ThemeProvider from styled-components with the new Primer React ThemeProvider:
    - import {ThemeProvider} from 'styled-components'
- import {theme} from '@primer/react
+ import {ThemeProvider} from '@primer/react'

function App() {
  return (
-   <ThemeProvider theme={theme}>
+   <ThemeProvider>
      <div>your app here...</div>
    </ThemeProvider>
  )
}
    • The structure of the theme object has changed to support color schemes:
    const theme = {
- colors,
- shadows,
+ colorSchemes: {
+   light: {
+     colors,
+     shadows,
+   },
+   dark: {...},
+   dark_dimmed: {...},
+ },
  space,
  fonts,
  fontSizes,
  fontWeights,
  lineHeights,
  borderWidths,
  radii,
  breakpoints,
  sizes,
}
    • The theme.colors and theme.shadows objects are no longer available from the theme export. Use the useThemehook instead:
    - import {theme} from '@primer/react'
+ import {useTheme} from '@primer/react'

function Example() {
+ const {theme} = useTheme()
  const myColor = theme.colors.text.primary
  ...
}

Patch Changes

24.0.0

Major Changes

  • b9d9d245 #1068 Thanks @colebemis! - Remove propTypes in favor of TypeScript types

  • beef075e #1094 Thanks @colebemis! - Components no longer have a default theme prop. To ensure components still render correctly, you'll need pass the Primer theme to a styled-components <ThemeProvider> at the root of your application:

    import {ThemeProvider} from 'styled-components'
import {theme} from '@primer/react'

function App(props) {
  return (
    <div>
      <ThemeProvider theme={theme}>
        <div>your app here</div>
      </ThemeProvider>
    </div>
  )
}

Patch Changes

23.2.1

Patch Changes

  • a42162c0 #1087 Thanks @emplums! - Fix up styles in TabNav allowing for items positioned on the right end of TabNav

23.2.0

Minor Changes

Patch Changes

23.1.0

Minor Changes

Patch Changes

23.0.4

Patch Changes

23.0.3

Patch Changes

23.0.2

Patch Changes