NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm · #1920 most downloaded on npm
> Simple styling in React.
Last release 2 years ago
no release in 18 months
Release timing varies
gaps range from 8 days to 7 months
Nearly every release is documented
notes for 32 of 32 stable releases
Nothing withdrawn
no release was ever pulled
7 years old
42 releases · first in 2020
One column per quarter.
Updated dependencies [ e1bf17e ]:
Updated dependencies [ 77d930d ]:
#3270 77d930d Thanks @emmatown! - Fix inconsistent hashes using development vs production bundles/exports conditions when using @emotion/babel-plugin with sourceMap: true (the default). This is particularly visible when using Emotion with the Next.js Pages router where the development condition is used when bundling code but not when importing external code with Node.js.
Updated dependencies [77d930d]:
### Patch Changes - #3232 `0ce3ed0` Thanks @ENvironmentSet! - Distribute css prop attachment over props that are union types - Updated dependencies []
#3232 0ce3ed0 Thanks @ENvironmentSet! - Distribute css prop attachment over props that are union types
Updated dependencies []:
Development builds (and other environment-specific builds) can be used by using proper conditions (see here). Most modern bundlers/frameworks already
#3198 d8ff8a5 Thanks @Andarist! - Migrated away from relying on process.env.NODE_ENV checks to differentiate between production and development builds.
Development builds (and other environment-specific builds) can be used by using proper conditions (see here). Most modern bundlers/frameworks already preconfigure those for the user so no action has to be taken.
Default files should continue to work in all environments.
#3215 a9f6912 Thanks @Andarist! - Added edge-light and workerd conditions to package.json manifest to better serve users using Vercel Edge and Cloudflare Workers.
Updated dependencies [`9ca22c6`, `b1d16b0`, `16d8a8c`]:
65a1eea Thanks @srmagura! - Automatic labeling at runtime is now an opt-in feature. Define globalThis.EMOTION_RUNTIME_AUTO_LABEL = true before Emotion gets initialized to enable it.#3206 d1994c4 Thanks @DiegoAndai! - Improved compatibility with the upcoming @types/react for React 19 where the global JSX namespace doesn't exist anymore
#3208 56109e7 Thanks @Andarist! - Only forward defined refs to improve compatibility with the upcoming React 19
Updated dependencies [9ca22c6, b1d16b0, 16d8a8c]:
### Patch Changes - #3159 `5b82631d` Thanks @iegik! - Renamed an internal hasOwnProperty to hasOwn. This avoids problems in CommonJS environments when
Updated dependencies [`45c440fb`]:
### Patch Changes - #3048 `9357f337` Thanks @naari3! - Added ElementType to the Emotion's JSX namespace. It's defined in the same way as the one in @t
Updated dependencies [`336f3d50`, `eed5e6cf`, `336f3d50`]:
Updated dependencies [`6bd13425`, `6bd13425`]:
Updated dependencies [`4e172c2a`]:
Updated dependencies [`13afe030`, `c02b1214`, `d8a13bca`]:
Note that we don't recommend bundling Emotion. You should have very specific reasons to do so.
#2867 89b6dbb3 Thanks @Andarist! - Externalized code referencing React.useInsertionEffect to a separate @emotion/use-insertion-effect-with-fallbacks package. This package should be used in your defined externals if you bundle Emotion for whatever reason. It references useInsertionEffect in a very specific way that allows us to use it conditionally. However, if the code consuming Emotion is bundled as a library with Emotion in it then some bundlers might change the way in which we reference useInsertionEffect and that might create problems for bundlers used to consume the said library code. By externalizing this new package you can still bundle Emotion if you want to without running into this problem as you won't "destroy" the carefully crafted reference to useInsertionEffect in the process.
Note that we don't recommend bundling Emotion. You should have very specific reasons to do so.
Updated dependencies [89b6dbb3]:
Updated dependencies [`bbad8c79`, `bbad8c79`]:
bbad8c79 Thanks @nicksrandall! - exports field has been added to the package.json manifest. It limits what files can be imported from a package but we've tried our best to allow importing all the files that were considered to be a part of the public API.bbad8c79 Thanks @nicksrandall! - Thanks to the added exports field, the package now includes a worker condition that can be utilized by properly configured bundlers when targeting worker-like environments. It fixes the issue with browser-specific files being prioritized by some bundlers when targeting workers.Updated dependencies [`26e4e3e8`, `6c2d7a60`, `5e81f213`]:
Updated dependencies [`d9357621`]:
#2700 d9357621 Thanks @arturmuller! - Fixed a false positive warning for content properties that included var().
Updated dependencies [d9357621]:
### Patch Changes - #2677 `ff3cb164` Thanks @Jack-Works! - Change Global component to use the StyleSheet constructor of the current cache.sheet. This
ff3cb164 Thanks @Jack-Works! - Change Global component to use the StyleSheet constructor of the current cache.sheet. This is useful when cache.sheet is not the default implementation. Thanks to that the inner sheet constructed by Global can share the behavior with its "main" sheet that is hold by the cache.### Patch Changes - #2651 `39ac5b99` Thanks @Andarist! - Fixed a transpilation issue that caused useInsertionEffect to be referenced directly in the s
Updated dependencies [`2f27156a`]:
2f27156a Thanks @Andarist! - Refactored code to use the upcoming React.useInsertionEffect when it's available (this is a new hook that is going to be introduced in React 18). This shouldn't have any effect on existing codebases and the change should be transparent.Updated dependencies [`1554a7e2`]:
04681a5f Thanks @Methuselah96! - Export Keyframes type to avoid TypeScript inserting import("@emotion/serialize").Keyframes references into declaration files emitted based on a source files exporting keyframes result. This avoids issues with strict package managers that don't allow accessing undeclared dependencies.### Patch Changes - #2534 `57be9e8c` Thanks @srmagura! - Changed the implementation of the runtime label extraction in elements using the css prop (th
57be9e8c Thanks @srmagura! - Changed the implementation of the runtime label extraction in elements using the css prop (that only happens in development) to one that should yield more consistent results across browsers. This fixes some minor issues with React reporting hydration mismatches that wouldn't happen in production.Updated dependencies [`9e82a991`, `516fe458`]:
Updated dependencies [`e5beae8e`, `9ae4a91a`, `f2eda829`]:
e5beae8e Thanks @Andarist! - Fixed an edge case issue with incorrect rules being generated. When a context selector (&) was used not at the beginning of a selector (which is not valid SCSS but is allowed by the Stylis parser that we are using) within a group of selectors containing a pseudoclass then it was not replaced correctly with the current context selector.Updated dependencies [`405af5ca`]:
24557d9d Thanks @garronej! - Exposed __unsafe_useEmotionCache which can be used to access the current Emotion's cache in an easier way than before. Using this might break 0-config SSR and is not recommended to be used unless there you know what you are doing and you are OK with the mentioned downside.cd25b62d Thanks @tills13! - Use theme context when rendering components at all times. This removes a conditional usage of a React hook that could break Rules of Hooks in some scenarios.Updated dependencies [`38f9d44f`]:
`4d2e732e` #2206 Thanks @jimmydief! - Added export for SerializedStyles Flow type.
4d2e732e #2206 Thanks @jimmydief! - Added export for SerializedStyles Flow type.`71ca9be3` #2181 Thanks @101arrowz! - Fixed some typing issues with React components with custom generic render functions.
71ca9be3 #2181 Thanks @101arrowz! - Fixed some typing issues with React components with custom generic render functions.`704b0092` #2180 Thanks @Andarist! - Fixed an issue with global styles containing pseudo selectors in at-rules not being able to be inserted.
`3f8bf70e` #2132 Thanks @dcastil! - displayNames have been added to Global and ClassNames components so React Developer Tools should display those bet
3f8bf70e #2132 Thanks @dcastil! - displayNames have been added to Global and ClassNames components so React Developer Tools should display those better now.`fdd46bdf` #2112 Thanks @Andarist! - Fixed the latest tree-shakeability improvements by adding "sideEffects": false to all internal package.json files
fdd46bdf #2112 Thanks @Andarist! - Fixed the latest tree-shakeability improvements by adding "sideEffects": false to all internal package.json files as well. This fixes hoist-non-react-statics not being dropped correctly despite of the latest improvements.`0e465d1c` #2101 Thanks @Andarist! - Improved tree-shakeability of the package. The main benefit is that bundlers should be able now to drop `hoist-no
0e465d1c #2101 Thanks @Andarist! - Improved tree-shakeability of the package. The main benefit is that bundlers should be able now to drop hoist-non-react-statics if you don't actually use our withTheme export.It has been completely rewritten and comes with some breaking changes. The most notable ones that might affect Emotion users are:
b8476e08 #1675 Thanks @emmatown! - Rename @emotion/core to @emotion/react. Please change any imports of @emotion/core to import @emotion/react or use the @emotion/pkg-renaming ESLint rule from @emotion/eslint-plugin.cbb8b796 #1628 Thanks @Andarist! - emotion-theming has been removed and all its exports were moved to @emotion/react package. Please import them like this import { useTheme, ThemeProvider, withTheme } from '@emotion/react' from now on.a72e6dc #1501 Thanks @JakeGinnivan! - TypeScript types have been significantly restructured. These changes:
css function has been restricted to prevent passing invalid typesstyled's generic parameter has been changed, if you were specifying the ComponentType you will need to remove that generic parameterstyled no longer takes a second ExtraProps parameter - instead of that move it to after the styled call. So instead of writing styled<typeof MyComponent, ExtraProps>(MyComponent)({}) you should now be writing styled(MyComponent)<ExtraProps>({})If you encounter build issues after upgrade, try removing any manually specified generic types and let them be inferred.
c6431074 #1609 Thanks @tomsseisums! - It's now easier to provide a type for Theme. Instead of creating custom instances (like before) you can augment the builtin Theme interface like this:
import '@emotion/react'
declare module '@emotion/react' {
export interface Theme {
primaryColor: string
secondaryColor: string
}
}
f57a7229 #1941 Thanks @Andarist! - The way in which we provide TypeScript support for the css prop has changed. Based on the usage of our JSX factories, we can add support for css prop only for components that support className prop (as our JSX factory functions take the provided css prop, resolve it and pass the generated className to the rendered component).
For the classic runtime this has been implemented using technique described here. What is important - we no longer extend any global interfaces, so people shouldn't bump anymore into type conflicts for the css prop when using different libraries with css prop support, such as styled-components.
For the automatic runtime this has been implemented by exporting JSX namespace from the appropriate entries but this is only supported in TypeScript 4.1 or higher.
However, if you are stuck with older version of TypeScript or using the classic runtime implicitly by using our @emotion/babel-preset-css-prop then it's not possible to leverage leverage css prop support being added conditionally based on a type of rendered component. For those cases we have added a special file that can be imported once to add support for the css prop globally, for all components. Use it like this:
/// <reference types="@emotion/react/types/css-prop" />
In this particular case we are forced to extend the existing React.Attributes interface. Previously we've been extending both React.DOMAttributes<T> and JSX.IntrinsicAttributes. This change is really minor and shouldn't affect any consuming code.
843bfb11 #1630 Thanks @Andarist! - Removed default export from @emotion/css - it's main purpose was to allow css to be a Babel macro, but since babel-plugin-macros allows us to keep imports nowadays this is no longer needed. @emotion/react/macro has been added to account for this use case and appropriate changes has been made to @emotion/babel-plugin to facilitate those changes.
If you have used @emotion/css directly (it was always reexported from @emotion/react) or you have been using its macro then you should update your code like this:
-import css from '@emotion/css'
+import { css } from '@emotion/react'
// or
-import css from '@emotion/css/macro'
+import { css } from '@emotion/react/macro'
You can also use the @emotion/pkg-renaming ESLint rule from @emotion/eslint-plugin to do this for you.
79036056 #967 Thanks @emmatown! - Use hooks internally for improved bundle size and a better tree in React DevTools9e998e37 #1817 Thanks @Andarist! - The parser we use (Stylis) got upgraded. It fixes some long-standing parsing edge cases while being smaller and faster 🚀
It has been completely rewritten and comes with some breaking changes. The most notable ones that might affect Emotion users are:
prefix option. This was always limited to turning off all of some of the prefixes as all available prefixes were on by default. The prefix option is gone and to customize which prefixes are applied you need to fork (copy-paste) the prefixer plugin and adjust it to your needs. While this being somewhat more problematic to setup at first we believe that the vast majority of users were not customizing this anyway. By not including the possibility to customize this through an extra option the final solution is more performant because there is no extra overhead of checking if a particular property should be prefixed or not.stylisPlugins. If you plan to use custom stylisPlugins and you want to have your styles prefixed automatically you must include prefixer in your custom stylisPlugins. You can import prefixer from the stylis module to do that.@import rules are no longer special-cased. The responsibility to put them first has been moved to the author of the styles. They also can't be nested within other rules now. It's only possible to write them at the top level of global styles.105de5c8 #1572 Thanks @Andarist! - [data-emotion] attribute on SSRed styled has changed. You should never rely on it though.
cf56694 #2088 Thanks @Andarist! - UMD filenames have been changed.
c672175b #1130 Thanks @jtmthf! - Support functions in arrays passed to css prop and Global's styles prop. This allows for composition of theme-accepting functions.828111cd #1639 Thanks @Andarist! - Global imported from macro entry (@emotion/react/macro) gets source maps generated now when inline css-less expression is used as value of the styles prop.5d692a6a #1956 Thanks @eps1lon! - Upgraded csstype dependency to its v3. This is what we use to provide TypeScript typings for object styles. The upgrade should not affect any consuming code but it's worth mentioning if any edge case scenarios arise.7dea6d7a #1734 Thanks @Andarist! - Fixed styles inserted by <Global/> component not inheriting speedy option from a cache passed to a wrapping <CacheProvider/>.
5c55fd17 #1653 Thanks @Andarist! - Fix to what location generated source maps are pointing in case of composed styles.
75e2f9e1 #1810 Thanks @Andarist! - Add a dev-only warning about styles created with css from @emotion/react being passed to cx from <ClassNames/>.d62d9101 #1677 Thanks @ajs139! - Warn if @emotion/react is initialized more than once in the same development environment.
a085003d #1613 Thanks @Andarist! - Add missing #__PURE__ annotations
`9c4ebc16` #2030 Thanks @Andarist! - Release candidate version.
Updated dependencies [`42df3f3b`, `42df3f3b`]:
Updated dependencies [`76e3dc4d`]:
76e3dc4d]:
`58b2bbca` #1981 Thanks @Andarist! - Changed the key of the global flag that helps us identify that @emotion/react has been loaded more than once to i
58b2bbca #1981 Thanks @Andarist! - Changed the key of the global flag that helps us identify that @emotion/react has been loaded more than once to include the current major version of @emotion/react.
Updated dependencies [a8eb4e75, dfe98028, debaad9a, 39be057b, 39be057b]:
`5d692a6a` #1956 Thanks @eps1lon! - Upgraded `csstype` dependency to its v3. This is what we use to provide TypeScript typings for object styles. The
`58dc08a6` #1837 Thanks @arcanis! - Fixed TS compatibility under PnP environments by making @types/react an optional peer dependency.
58dc08a6 #1837 Thanks @arcanis! - Fixed TS compatibility under PnP environments by making @types/react an optional peer dependency.f57a7229 #1941 Thanks @Andarist! - The way in which we provide TypeScript support for css prop has changed. Based on usage of our jsx pragma we are able to add support for css prop only for components that support className prop (as our jsx factory function takes provided css prop, resolves it and pass the generated className to the rendered component). This has been implemented using technique described here. What is important - we no longer extend any global interfaces, so people shouldn't bump anymore into type conflicts for the css prop when using different libraries with the css prop support, such as styled-components.
However, it's not possible to leverage css prop support being added conditionally based on a type of rendered component when one is not using our jsx pragma. For those cases when people use our pragma implicitly (for example when using our @emotion/babel-preset-css-prop) we have added special file that can be imported once to add support for the css prop globally, for all components. Use it like this:
import {} from '@emotion/react/types/css-prop'
In this particular case we are forced to extend the existing React.Attributes interface. Previously we've been extending both React.DOMAttributes<T> and JSX.IntrinsicAttributes. This change is really minor and shouldn't affect any consuming code.
Updated dependencies [4d3b60d0, 58dc08a6, 6d32d82b]:
It has been completely rewritten and comes with some breaking changes. Most notable ones that might affect Emotion users are:
9e998e37 #1817 Thanks @Andarist! - The parser we use (Stylis) got upgraded. It fixes some long-standing parsing edge cases while being smaller and faster 🚀
It has been completely rewritten and comes with some breaking changes. Most notable ones that might affect Emotion users are:
prefix option. This was always limited to turning off all of some of the prefixes as all available prefixes were on by default. The prefix option is gone and to customize which prefixes are applied you need to fork (copy-paste) the prefixer plugin and adjust it to your needs. While this being somewhat more problematic to setup at first we believe that the vast majority of users were not customizing this anyway. By not including the possibility to customize this through an extra option the final solution is more performant because there is no extra overhead of checking if a particular property should be prefixed or not.stylisPlugins. If you plan to use custom stylisPlugins and you want to have your styles prefixed automatically you must include prefixer in your custom stylisPlugins. You can import prefixer from the stylis module to do that.@import rules are no longer special-cased. The responsibility to put them first has been moved to the author of the styles. They also can't be nested within other rules now. It's only possible to write them at the top level of global styles.`105de5c8` #1572 Thanks @Andarist! - [data-emotion] attribute on SSRed styled has changed. You should never rely on it though.
105de5c8 #1572 Thanks @Andarist! - [data-emotion] attribute on SSRed styled has changed. You should never rely on it though.7dea6d7a #1734 Thanks @Andarist! - Fixed styles inserted by <Global/> component not inheriting speedy option from a cache passed to a wrapping <CacheProvider/>.be2eb614 #1806 Thanks @Andarist! - Do not warn about @emotion/react being loaded twice in Jest. For some reason Jest sometimes evaluates modules twice when jest.mock is being called.75e2f9e1 #1810 Thanks @Andarist! - Add a dev-only warning about styles created with css from @emotion/react being passed to cx from <ClassNames/>.
Updated dependencies [e3d7db87, 105de5c8, 105de5c8, 5bea60b1, 105de5c8, 105de5c8]:
Updated dependencies [`f08ef5a3`, `b79781f8`]:
`b8476e08` #1675 Thanks @emmatown! - Rename @emotion/core to @emotion/react. Please change any imports of @emotion/core to import @emotion/react or us
b8476e08 #1675 Thanks @emmatown! - Rename @emotion/core to @emotion/react. Please change any imports of @emotion/core to import @emotion/react or use the @emotion/pkg-renaming ESLint rule from @emotion/eslint-plugin.affed3dd #1702 Thanks @Andarist! - Fix issue with published TypeScript test files augmenting Theme interface.d62d9101 #1677 Thanks @ajs139! - Warn if @emotion/react is initialized more than once in the same development environment.1e4a741d, 2fa7a213, b8476e08, dfe79aca, b8476e08, b8476e08, b8476e08, dfe79aca]:
Your coding agent can read these notes before it upgrades. Set up the MCP server →