Primer React v38 Release: Faster, lighter, and more accessible

[francinelucca]

Primer React v38 is here, a major update focused on improving performance. The highlight of this release is our move from styled-components to CSS Modules, which reduces JavaScript bundle sizes and enhances both client and server-side rendering performance.

✨ What's New

The following component has been promoted from @primer/react/experimental to @primer/react:

• Banner: Now stable and ready for production use.

Other updates:

• ActionBar:
  • Now supports groups through the ActionBar.Group subcomponent
  • Now supports gap prop for customizable spacing between items
• Banner: Now supports actionsLayout prop to handle actions layout edge cases
• Breadcrumbs: Adds overflow menu for responsive behavior
• ConfirmationDialog: Now supports overrideButtonFocus to allow changing initially focused button
• SegmentedControl.Button: Now supports count
• ToggleSwitch: Now supports customizing labels by state through buttonLabelOn, buttonLabelOff props
• Tooltip: Adds delay functionality to tooltips with the options of instant (default), medium, long
• Treeview.Item: Now supports secondaryActions

💥 Breaking Changes

We’ve removed our dependency on the end-of-life library styled-components. This means some component styling will need to change:

• The sx prop is no longer supported. You can style components by providing a className and using CSS Modules.
• Props from styled-system are no longer available.
• Support for theming in JavaScript has been removed.

Deprecated Components

The following components are now deprecated and will be removed in a future release:

• CircleBadge
  • Replace the component with icon imports from @primer/octicons-react and utilize custom styling.
• TextInputWithTokens
  • The component has been moved to the deprecated entrypoint due to low usage and accessibility implications. Import from @primer/react/deprecated instead of @primer/react.

Removed Components

The following deprecated components have been removed from Primer React:

• AvatarPair
  • Use the Avatar or AvatarStack component from @primer/react instead
• AvatarToken
  • Use Token with leadingVisual and an Avatar from @primer/react instead
• Caret
  • This component is now maintained internally
• CircleOcticon
  • Replace the component with icon imports from @primer/octicons-react and utilize custom styling.
• PointerBox
  • This component is no longer necessary and can be removed
• Box
  • This component is no longer necessary and can be removed

Removed Props

The following props are no longer supported:

• Popover: no longer supports overflow property
• SegmentedControl.Button: deprecated leadingIcon in favor of leadingVisual
• Select: contrast prop is no longer supported

Change to ESM Only

The @primer/react package now publishes only ESM (ECMAScript Modules) artifacts. This should have minimal impact, as modern versions of Node.js support require()'ing ESM modules.

🛠️ Migration and Compatibility

If you are using components or utilities that rely on styled-system props or theme being available via context, for example: Box, sx or useTheme, you will need to update your codebase to remove these dependencies (prefer to use CSS modules over styled-components and css variables over javascript theming) prior to adopting v38. If you’re looking to upgrade to v38 while still supporting styled-components, drop us a comment below, we’d love to hear from you!

If you’re using Primer theming, take a look at our Migrating to CSS variables compatibility guide.

See the full changelog for a detailed recount of every change included in v38. 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.