The 4.0.0-beta release renames some components:
FlexContainer
is now namedFlex
FlexItem
is nowFlex.Item
UnderlineNavItem
is nowUnderlineNav.Item
FilterListItem
is nowFilterList.Item
There is a codemod available to upgrade component identifiers from v3.x.x-beta:
npx jscodeshift -t node_modules/@primer/components/codemods/v4.js path/to/src
The following breaking changes must be accounted for manually:
Label
no longer has ascheme
prop, but now respectssize
anddropshadow
props.StateLabel
does have ascheme
prop (instead ofstate
), and takes different values.
🚨 As of v3, the name of the package has changed from primer-react
to @primer/components
.
The 3.0.0-beta release contains the following breaking changes:
- The
MergeStatus
component is gone. Use aStateLabel
instead. - The
Link
component no longer acceptsscheme
ormuted
props, and has no underline by default. DonutChart
is now simplyDonut
, andDonutSlice
isDonut.Slice
.
There is a codemod available to upgrade from 2.x.x-beta and updating the package name:
npx jscodeshift -t node_modules/@primer/components/codemods/v3.js path/to/src
The 2.0.0-beta release is a major version bump because it renames several components:
Box
is nowBorderBox
Block
is nowBox
CaretBox
is nowPointerBox
We suggest that you rename your components in the above order, since renaming Block
to Box
before renaming the old Box
component to BorderBox
will cause problems.
There is a codemod available to upgrade from 1.x.x-beta:
npx jscodeshift -t node_modules/primer-react/codemods/v2.js path/to/src
This release is a major version bump because it completely refactors the guts of all our components. Here's what you need to know:
There is a codemod available to upgrade from previous versions 0.x.x-beta
:
npx jscodeshift -t node_modules/primer-react/codemods/v1.js path/to/src
The big change in this release is the introduction of emotion and styled-system under the hood to speed up our migration from Primer CSS to complete style encapsulation in React. For now, you will need to continue serving up Primer CSS to support components that haven't yet been migrated to the new styling system. See the README for more information.
This release also introduces early support for theming.
-
The
tag
prop has been renamed tois
to match styled-system conventions. -
Color props will require refactoring:
-
The
fg
prop has been renamed tocolor
across the board. -
Color prop (
bg
,color
, andborderColor
) values are now object paths that represent nested fields in thecolors
object of our default theme. Because all of our color gradations are expressed as arrays, thegray
,blue
,green
,orange
,purple
,red
, andyellow
values need to be updated to include the.5
suffix so that they receive the value closest to the middle of each hue gradation (red.5
maps totheme.colors.red[5]
).In other words,
color="red"
becomescolor="red.5"
,bg="purple"
becomesbg="purple.5"
, and so on. See the full list of changes below.
-
-
Some typography props will require refactoring.
-
Some
Block
props have changed. -
Some
FlexContainer
andFlexItem
props have changed.
Theming is an optional way to override the values that control color, spacing, typography, and other aspects of our components.
There are two ways to change the theme of @primer/components components:
-
You can override the theme for an entire tree of components using the
<ThemeProvider>
from emotion-theming:import {Block, Button, Text, theme as primer} from '@primer/components' import {ThemeProvider} from 'emotion-theming' // a theme with custom spacing and font sizes const theme = { ...primer, space: [0, 8, 16, 32, 64], fontSizes: [10, 12, 16, 24, 48], } // override theme.colors.bodytext = '#111' export default () => ( <ThemeProvider theme={theme}> <Block sx={{color: 'bodytext', p: 4}}> <Text fontSize={4}>Hello, world!</Text> </Block> </ThemeProvider> )
⚠️ Note: emotion-theming's<ThemeProvider>
only allows exactly one child. -
You can theme individual components by passing the
theme
prop directly:import {Text} from '@primer/components' const theme = { colors: { magenta: '#f0f', }, } export default () => ( <Text theme={theme} color="magenta"> Hi, I'm magenta! </Text> )
☝️ This is an intentionally convoluted example, since you can use
<Text color='#f0f'>
out of the box.
Read the styled-system docs for more information on theming in styled-system.
The following table lists color prop values that have changed in 1.0.0-beta
:
Prop | Before | After | Notes |
---|---|---|---|
bg |
blue-light |
blue.0 |
|
bg |
blue |
blue.5 |
|
bg |
gray-dark |
gray.9 |
|
bg |
gray-light |
gray.0 |
|
bg |
gray |
gray.1 |
|
bg |
green-light |
green.1 |
|
bg |
green |
green.5 |
|
bg |
orange |
orange.7 |
|
bg |
purple-light |
purple.0 |
|
bg |
purple |
purple.5 |
|
bg |
red-light |
red.1 |
|
bg |
red |
red.5 |
|
bg |
yellow-light |
yellow.2 |
|
bg |
yellow |
yellow.5 |
|
borderColor |
black-fade |
blackfade15 |
|
borderColor |
blue-light |
blue.2 |
|
borderColor |
blue |
blue.5 |
|
borderColor |
gray-dark |
gray.3 |
|
borderColor |
gray-darker |
gray.7 |
|
borderColor |
gray-light |
#eaecef |
Not yet migrated |
borderColor |
gray |
gray.2 |
|
borderColor |
green-light |
#a2cbac |
Not yet migrated |
borderColor |
green |
green.4 |
|
borderColor |
purple |
purple.5 |
|
borderColor |
red-light |
#cea0a5 |
Not yet migrated |
borderColor |
yellow |
#d9d0a5 |
Not yet migrated |
color |
blue |
blue.5 |
|
color |
gray-dark |
gray.9 |
|
color |
gray-light |
gray.5 |
|
color |
gray |
gray.6 |
|
color |
green |
green.5 |
|
color |
orange-light |
orange.6 |
|
color |
orange |
orange.9 |
|
color |
purple |
purple.5 |
|
color |
red |
red.6 |
Remember that all fg
props must be renamed to color
.
-
Typography props are still only available on the
Text
andHeading
components. -
The
fontSize
prop works as before, but now treats any value that doesn't represent an index oftheme.fontSizes
as a literal CSS value. -
The
lineHeight
prop now accepts one of the keys fromtheme.lineHeights
:default
,condensed
, orcondensedUltra
. Any other value will be passed along as a literal CSS value.
The following table lists typography-related prop substitutions:
Prop | Value(s) | Substitute |
---|---|---|
lineHeight |
condensed-ultra |
lineHeight="condensedUltra" |
mono |
(boolean) | fontFamily="mono" |
nowrap |
(boolean) | css="white-space: nowrap" |
The Block
component supports most of the same props, but the following ones will need to be refactored:
Prop | Value(s) | Substitute |
---|---|---|
border |
true |
border={1} |
border |
'bottom' |
borderBottom={1} |
border |
'left' |
borderLeft={1} |
border |
'right' |
borderRight={1} |
border |
'top' |
borderTop={1} |
shadow |
all | boxShadow="value" |
Note: array values in border props represent responsive values.
The FlexContainer
and FlexItem
components have changed significantly in this version. The following props have been renamed or deprecated:
Prop | Value(s) | Substitute |
---|---|---|
direction |
all | flexDirection="css-value" |
wrap |
wrap , nowrap |
flexWrap="css-value" |
inline |
(boolean) | display="inline-flex" |
Prop | Value(s) | Substitute |
---|---|---|
flexAuto |
(boolean) | No longer supported |
Codemods are scripted transformations that you can run on your code to relieve you of most of the grunt work involved in upgrading from one major version to the next. The codemod instructions for each major release assume that your code has already been upgraded to the previous major release. If this is not the case, you should run the codemods for all previous major versions first.
Beware that codemods are not 100% fool-proof and may break your code, especially if you do unexpected things like alias Primer exports in strange ways (import {Box as box}...
), or use component identifiers from other modules that conflict with Primer's. Before running a codemod, please either back up your work or commit it, then carefully inspect the diff.