Primer React v36 Release

[joshblack]

We're excited to announce the next major release of Primer React! 🥳 Starting in v36, you'll see changes to @primer/react that make it even easier to build consistent, accessible experiences that feel right at home at GitHub.

We'd love to hear from you and get feedback on these changes. Let us know in a comment below if you run into any bugs, if a change to a component you were using. is unclear, or if you have any other feedback about this release.

New components ✨

The following components have been moved from @primer/react/drafts to @primer/react:

• TreeView
• NavList
• SegmentedControl
• SplitPageLayout

Breaking changes ⚠️

The v36 release of @primer/react introduces several breaking changes to components and changes to the package itself. To understand how to migrate between v35 and v36 of @primer/react, review the sections below to understand how your project may be impacted by these changes.

Components

The following list of components have breaking changes to their API or availability in @primer/react. For a list of deprecated components that have been removed, visit the Removed components section below.

• AvatarToken
• Button
• Checkbox
• FilterList
• FilterSearch
• FormControl
• Radio
• Textarea
• TextInputWithTokens
• UnderlineNav

AvatarToken

The size prop for AvatarToken has been updated in v36 to only accept "large" and "xlarge".

v35	v36
<AvatarToken size="small"> <AvatarToken size="medium"> <AvatarToken size="large"> <AvatarToken size="xlarge"> <AvatarToken size="extralarge">	<AvatarToken size="large"> <AvatarToken size="xlarge">

Button

The API for the Button component has been updated to match the specification for this component and align with other implementations like in Primer View Components.

• The leadingIcon prop has been renamed to leadingVisual

  v35	v36
  <Button leadingIcon={TrashIcon}>Delete</Button>	<Button leadingVisual={TrashIcon}>Delete</Button>

• The trailingIcon prop has been renamed to trailingVisual

  v35	v36
  <Button trailingIcon={EyeIcon}>Delete</Button>	<Button trailingVisual={EyeIcon}>Delete</Button>

• The Button.Counter component has been removed, use the count prop instead

  v35	v36
  <Button> Watch <Button.Counter>5</Button.Counter> </Button>	<Button count={5}>Watch</Button>

• The outline variant has been removed, instead use variant="invisible"

  v35	v36
  <Button variant="outline">Example</Button>	<Button variant="invisible">Example</Button>

Checkbox

The validationStatus prop has been updated and no longer supports the 'warning' value. Instead, only 'error' and 'success' are supported.

FilterList

The FilterList component has been deprecated in v36 in favor of the ActionList component. To continue using this component, update your imports for FilterList to import from the deprecated entrypoint.

v35	v36
import { FilterList } from '@primer/react';	import { FilterList } from '@primer/react/deprecated';

FilterSearch

The FilterSearch component has been deprecated in v36. A new filter component is currently in progress but is not yet available. Until a new component is ready, use a combination of Button, TextInput, and ActionList to reproduce this component. To continue using this component, update your imports for FilterSearch to import from the deprecated entrypoint.

v35	v36
import { FilterSearch } from '@primer/react';	import { FilterSearch } from '@primer/react/deprecated';

FormControl

The variant prop for the FormControl.Validation component has been updated to no longer support the 'warning' value. Instead, only 'error' and 'success' are supported.

Radio

The validationStatus prop has been updated and no longer supports the 'warning' value. Instead, only 'error' and 'success' are supported.

Textarea

The validationStatus prop has been updated and no longer supports the 'warning' value. Instead, only 'error' and 'success' are supported.

TextInputWithTokens

The size prop has been updated to no longer accept the extralarge value. Use xlarge instead.

v35	v36
<TextInputWithTokens size="extralarge">	<TextInputWithTokens size="xlarge">

UnderlineNav

The implementation for UnderlineNav has been updated in v36. Certain props for UnderlineNav have been removed and the UnderlineNav.Link component has been replaced by UnderlineNav.Item.

Component	v35	v36
UnderlineNav	actions	This prop has been removed
	align	This prop has been removed
	full	This prop has been removed
UnderlineNav.Link		Use the UnderlineNav.Item component
UnderlineNav.Link	selected	Use the aria-current prop

v35	v36
<UnderlineNav aria-label="Main"> <UnderlineNav.Link href="#home" selected> Home </UnderlineNav.Link> <UnderlineNav.Link href="#documentation"> Documentation </UnderlineNav.Link> <UnderlineNav.Link href="#support"> Support </UnderlineNav.Link> </UnderlineNav>	<UnderlineNav aria-label="Main"> <UnderlineNav.Item href="#home" aria-current="page"> Home </UnderlineNav.Item> <UnderlineNav.Item href="#documentation"> Documentation </UnderlineNav.Item> <UnderlineNav.Item href="#support"> Support </UnderlineNav.Item> </UnderlineNav>

To continue using the implementation for UnderlineNav from v35, import the component from @primer/react/deprecated.

v35	v36
import { UnderlineNav } from '@primer/react';	import { UnderlineNav } from '@primer/react/deprecated';

Removed components

The following deprecated components have been removed from @primer/react and are no longer available.

Name	Migration
BorderBox	Use the Box component, <BorderBox> → <Box borderWidth='1px' borderStyle='solid' borderColor='border.primary' borderRadius={2}>
ChoiceFieldset	Use the CheckboxGroup or RadioGroup component
Item	Use CheckboxGroup or RadioGroup component
ChoiceInputField	Use the FormControl component
Flex	Use the Box component, <Flex> → <Box display="flex">
Grid	Use the Box component, <Grid> → <Box display="grid">
Position	Use the Box component, <Position> → <Box>
Absolute	Use the Box component, <Absolute> → <Box position="absolute">
Fixed	Use the Box component, <Fixed> → <Box position="fixed">
Relative	Use the Box component, <Relative> → <Box position="relative">
Sticky	Use the Box component, <Sticky> → <Box position="sticky">
Dropdown	Use the ActionMenu component
FormGroup	Use the FormControl component
InputField	Use the FormControl component
Label	Use the updated Label component from the @primer/react entry point
SelectMenu	Use the ActionMenu component
ActionList	Use the updated ActionList component from the @primer/react entry point
ActionMenu	Use the updated ActionMenu component from the @primer/react entry point
DropdownButton	Use the ActionMenu component
DropdownMenu	Use the ActionMenu component
Button	Use the updated Button component from the @primer/react entry point
ButtonDanger	Use the updated Button component with variant="danger"
ButtonOutline	Use the updated Button component with variant="outline"
ButtonPrimary	Use the updated Button component with variant="primary"
ButtonInvisible	Use the updated Button component with variant="invisible"
ButtonTableList	Use the ActionMenu component
ButtonClose	Use the IconButton component, <IconButton icon={XIcon} aria-label="Close" />
StyledOcticon	Use the Octicon component

Package 📦

Changes to peer dependencies 🏗️

The following peer dependencies have been updated, or added, to require a new minimum version in v36 of @primer/react:

Package	v35	v36
react	^17.0.0 || ^18.0.0	^18.0.0
react-dom	^17.0.0 || ^18.0.0	^18.0.0
styled-components	4.x || 5.x	5.x
@types/styled-components	Not available	5.x

These dependencies will need to be updated or installed in your project if you are not using the corresponding version range for v36. To see if you're using the correct versions, look in your project's package.json file and see if the versions match the table above.

Note
If you're not using TypeScript in your project, feel free to ignore the @types dependencies above.

drafts has been moved to experimental

The drafts entrypoint has been deprecated in v35 and removed in v36. It has been replaced by the experimental entrypoint to better reflect the component lifecycle process for Primer.

v35	v36
import { ExampleComponent } from '@primer/react/drafts';	import { ExampleComponent } from '@primer/react/experimental';

[gr2m]

is it possible that StyledOcticon was removed in v36? It's not listed in the breaking changes

[joshblack]

Hey @gr2m! You're right, that was totally not included in the changelog (I'll add it in).

StyledOcticon is now just Octicon 👍