Migration Guides
v0.14
@theme-ui/components
and other Theme UI packagss no longe depends on@emotion/styled
.Previously deprecated
.withComponent
API was removed.as
prop was removed from Themed.X components from@theme-ui/mdx
.
v0.13
Moved Emotion and @mdx-js/react
to peerDependencies to solve context
mismatch bugs
You now install theme-ui
umbrella package like this:
npm install theme-ui @emotion/react @emotion/styled @mdx-js/react
@emotion/react
is now a peer dependency of the majority of Theme UI libraries@emotion/styled
is now a peer dependency of@theme-ui/components
,@theme-ui/mdx
, andtheme-ui
@mdx-js/react
is now a peer dependency of@theme-ui/mdx
andtheme-ui
This is a revert of change from Theme UI v0.3, and it's meant to help solve version clashes and context mismatch bugs on user side. Connected issues: #1793, #1531, #1530, #1388, #1345, #1130.
Disclaimer: You might still encounter this problem if other libraries install clashing Emotion versions.
Learn more at #1867.
v0.9
Dropped support for legacy browsers.
Theme UI packages became lighter! Built source code is now 9.5 kB (34%) smaller.
The trade-off is, Babel config has changed and it no longer supports Internet Explorer 11. If you need to support legacy browsers, you can transpile node_modules (e.g. with next-transpile-modules).
- See build raport with size comparison for each package
- Inspect updated Babel config
- Visit Bundlephobia
Internal package gatsby-theme-code-recipes
was removed.
v0.8
Theme configuration options were moved to theme.config
object.
Deprecations:
useRootStyles
,useCustomProperties
,useColorSchemeMediaQuery
,useBorderBox
, anduseLocalStorage
options on the theme object are now scoped under aconfig
object on the theme, and the root-level options, now deprecated, will be removed in a future release.(e.g. you should be setting
theme.config.useBorderBox
instead oftheme.useBorderBox
)- ⚠ All config options should be migrated at once. If Theme UI sees
theme.config
exists, it won't look for options on thetheme
.
- ⚠ All config options should be migrated at once. If Theme UI sees
APIs deprecated in v0.6 were removed.
theme.useBodyStyles
⟶theme.config.useRootStyles
Styled
⟶Themed
Following the deprecation of useBodyStyles
, useRootStyles
now defaults to
true. This means that your styles from theme.styles.root
are now applied to
<html>
element, not <body>
element. Most use cases should be fine, but some
styles may need adjustment.
v0.6
What's New
Styled
components dict was renamed toThemed
to avoid confusion withstyled
components constructors from@emotion/styled
and similar libraries.theme.useRootStyles
configuration option (false by default). Set it totrue
to addstyles.root
tohtml
instead ofbody
.theme.useBodyStyles
configuration option still defaults totrue
, but it's going in to be deprecated in favor oftheme.useRootStyles
in the future.
New scale:
transitions
supportingtransition
CSS property. Issue #1079, PR #1272Objects in nested scales can now have a
__default
key. PR #951Given the theme
const theme = {colors: {primary: {__default: '#00f',light: '#33f',}}}color: 'primary'
resolves tocolor: '#00f'
.Configuration option for printing color mode. PR #1267, issue #1144. No more wasted ink.
{initialColorModeName: "dark",printColorModeName: "light"}A new component, Paragraph was added in PR #1298
Breaking Changes
Theme UI 0.6 depends on Emotion 11, and isn't compatible with Emotion 10 anymore.
- If you didn't install Emotion separately, this update shouldn't affect you.
- If your other dependencies depend on Emotion 10, and have no published versions for Emotion 11, you can use Yarn resolutions or Webpack's resolve.alias to enforce a version.
Refer to Emotion 11 release notes for more information.
Color mode flash on first render is gone, but to achieve this we had to bring back
theme.rawColors
.- You can no longer read raw color values from
theme.colors
when reading theme fromuseThemeUI
or insidesx
. .colors
object contains Custom CSS Properties now.- If you need to pass original value somewhere where CSS Properties (e.g.
WebGL Canvas) won't work use
.rawColors
.
How to migrate?
Find places where you read
colors
from the useThemeUI and extractrawColors
instead ofcolors
.const { rawColors: colors } = useThemeUI().theme- You can no longer read raw color values from
Default color mode name is no longer
"default"
— it's nowundefined
, what represents the lack of color mode set by user or detected from preferences.useColorSchemeMediaQuery
defaults totrue
. Issue #624, PR #1373How to migrate? Add
useColorSchemeMediaQuery: false
to your theme if you don't have this property. Read more in the docs.We no longer export internal React context named as
Context
😅 It wasn't and it's still not public API, but if you used it and you really need it, you can grab it as__ThemeUIContext
. (But please don't do this. UseThemeProvider
from @theme-ui/core for local theme overrides instead.)
Deprecations
Styled
will be removed in v0.7. UseThemed
instead.useBodyStyles
will be removed in v0.7. UseuseRootStyles
instead.
TypeScript Changes
Theme UI is now written in TypeScript, and the emitted types differ from
@types/theme-ui
.
false
in now accepted in responsive tuple types. PR #1499Known colors (primary, text, background, accent, secondary) in
ColorMode
can now be nested scales.The following no longer typechecks, as
colors.primary
can be an object.sx={{color: theme => theme.colors?.primary?.toUpperCase()}}But the following code still works.
sx={{color: theme => theme.colors?.primary}}If
colors.primary
is an object,colors.primary.__default
is used.false
values are skipped before passing style objects to Emotion. Issue #1297, PR #1460.The following syntax is now supported
sx={{ color: isActive && blue }}"as" prop on Themed.X components now properly opts out of typechecking
- TypeScript users, don't use
ComponentProps<typeof Themed['div']>
, importThemedComponent
and useThemedComponent<'div'>
instead.
- TypeScript users, don't use
Theme UI 0.6 depends on
csstype
v3 instead ofcsstype
v2.Renamed types
- Anything copied from
styled-system
types was renamed or removed. SxProps
was renamed toSxProp
.SxStyleProp
, an alias forThemeUIStyleObject
was removed. UseThemeUIStyleObject
instead.
- Anything copied from
Refer to the changelog for a full list of changes.
v0.3
What's New
- Components can now be imported directly from the
theme-ui
package. Be sure that treeshaking is enabled with your build tool. - Includes smart defaults for adding base styles to the
<body>
element. - Simplified color modes API.
- New
@theme-ui/css
,@theme-ui/core
,@theme-ui/color-modes
, and@theme-ui/mdx
packages allow for more bespoke ways to use the library.
Breaking Changes
@emotion/react
and@mdx-js/react
are now dependencies oftheme-ui
and should not be installed separately. If you'd like to use a particular version of each library, use Yarn resolutions.- Theme UI context no longer provides
context.components
. If you're using this object from context, use the MDX hook instead. E.g.import { useMDXComponents } from '@mdx-js/react'
- If you'd like color mode to be initialized from the
prefers-color-scheme
media query, you must enable theuseColorSchemeMediaQuery: true
flag in your theme. - The
ColorMode
component is deprecated and no longer required to add color styles to the<body>
element. - The following components have been removed in favor of using
Box
andFlex
components:Layout
,Header
,Main
,Footer
- The
initialColorMode
flag no longer works, useinitialColorModeName
instead. - The
ThemeProvider
now adds global typographic styles to the<body>
element based ontheme.styles.root
. To disable this behavior set theuseBodyStyles: false
flag in your theme. - Theme context is now stateless. If you've made use of
context.setTheme
, this no longer works. An alternative approach is available with the@theme-ui/editor
package. - The
ThemeStateProvider
component is no longer avialable, see@theme-ui/editor
as an alternative. - The
@theme-ui/editor
package has a completely new API. Please refer to the package's README.md for more information.
v0.2
JSX Pragma
If you were using the Theme UI custom JSX pragma, rename the css
prop to sx
.
This does not apply if you were importing and using the css
utility function
manually.
theme-ui-typography
If you were using the theme-ui-typography
package, install the new package
named @theme-ui/typography
instead. The toStyle
API is no longer included.
Use the toTheme
API instead, see the
Typography.js docs for how to use this utility.
Box
and layout component
If you were using Styled System style props on the Box
component or any other
layout component, replace these props with either the sx
prop or
by using the css
utility.
Other
- Replace
ColorModeProvider
andComponentProvider
with theThemeProvider
component. - The
@emotion/styled
package is no longer required for Theme UI. If you are not using it directly in your application, you can remove it from your dependencies.