Migrating to Emotion
As part of the version 16.0.0 release, Halstack React now uses emotion as its internal styling engine. Previous versions relied on styled-components. This change improves performance, reduces bundle size, and aligns with the rest of the Halstack ecosystem. This page explains the required steps if your application relied on styled-components specific features, theme injections, or style overrides. If any topic is not covered here, please refer to the official Emotion documentation.
| Area | styled-components | emotion |
|---|---|---|
| Primary styling API | styled factory from styled-components | @emotion/styled |
| CSS prop | Not available by default | Available natively CSS prop |
| SSR insertion | ServerStyleSheet | @emotion/server (extractCritical) |
| Theme object | SC ThemeProvider | Emotion ThemeProvider |
Applications may need adjustments in the following areas:
- Local components using
styled-components. - Server-side rendering setups relying on
ServerStyleSheet. - Build setups using the Babel plugin for styled-components.
As stated in the Installation Page, the following packages must be added to your project:
npm i @emotion/react @emotion/styledWhile the following package must be removed from it:
npm un styled-componentsReplace imports from styled-components with @emotion/styled:
Previous version:
import styled from "styled-components";New version:
import styled from "@emotion/styled";The API of both works in the same way, so this should be the only required change. For further information, please refer to the official documentation
Theme context must now be provided using Emotion's ThemeProvider:
Previous version:
import { ThemeProvider } from "styled-components";New version:
import { ThemeProvider } from "@emotion/react";Emotion and styled-components have mostly compatible theming APIs, but theme propagation differs in some edge cases. In Emotion, deeply nested styled components always use the nearestThemeProvider without needing additional wrappers.
If your application relied on implicit theme merging or multiple nested theme layers from styled-components, verify that the theme structure is still correct after migrating.
Emotion supports the css prop natively. This prop can be used to apply styles directly to any component without needing to create a styled wrapper. For more information please refer to the official documentation
If your app uses SSR, replace ServerStyleSheet with Emotion's server utilities:
Previous version:
import { ServerStyleSheet } from "styled-components";New version:
import createEmotionServer from "@emotion/server/create-instance";
import { cache } from "@emotion/css"; // or emotion-cache if configured
const { extractCritical } = createEmotionServer(cache);If your application used createGlobalStyle from styled-components, it must be replaced with Emotion's Global component.
Previous version:
import { createGlobalStyle } from "styled-components";
const GlobalStyles = createGlobalStyle`
body {
margin: 0;
}
`;New version:
import { Global, css } from "@emotion/react";
const GlobalStyles = (
<Global
styles={css`
body {
margin: 0;
}
`}
/>
);