Primer React v36 Release Candidate

[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.

v36 will first be available through a number of Release Candidates. These early releases will be previews of the full release in order for teams to try out v36 and give the team feedback before our final release. To try out the latest release candidate, head over to Getting started. If you have any feedback or questions about this release, we'd love to hear from you in a comment below!

Getting started

To try out the latest Release Candidate for v36 of @primer/react, run the following command using npm:

npm install @primer/react@next-major

After updating to the latest version, go through the Breaking changes section below to make the necessary changes for your project.

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
• PageLayout
• 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.

PageLayout

The position prop has been removed from PageLayout.Pane in order to address an accessibility issue when ordering elements on a page with CSS. Instead of relying on position to order the different sections of PageLyout, use source order.

v35	v36
<PageLayout> <PageLayout.Content/> <PageLayout.Pane position="start" /> </PageLayout>	<PageLayout> <PageLayout.Pane /> <PageLayout.Content /> </PageLayout>

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/deprecated and are no longer be 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" />

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';