Installation

There are two main ways to install Cherry Styled Components into your project. You can either clone the main repository and customize the components to your liking, or install the library from npm.

Implementation Options

Install the Cherry library from npm along with its peer dependencies. Import components directly into your project. Perfect for smaller projects or rapid development. The library requires react and react-dom (^18 or ^19) and styled-components (^6) as peer dependencies.

npm install cherry-styled-components react react-dom styled-components

Clone the main Cherry repository. Dive into the components' code and customize to your heart's content. Ideal for extensive modifications.

git clone [email protected]:cherry-design-system/styled-components.git

Theme Context

Always wrap your application in the CherryThemeProvider component. Ensure that your theme prop is passed down correctly. For server-rendered apps that need flash-free dark mode, use ClientThemeProvider instead - see Dark Mode.

import { CherryThemeProvider, theme } from "cherry-styled-components";

export default function App({ children }) {
  return <CherryThemeProvider theme={theme}>{children}</CherryThemeProvider>;
}

Next.js Integration

When integrating into a Next.js app, first install the dependencies:

npm install cherry-styled-components react react-dom styled-components

Next, enable the styled-components compiler in your next.config.ts. This keeps class names deterministic between server and client renders and avoids hydration mismatches:

next.config.ts

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  compiler: {
    styledComponents: true,
  },
};

export default nextConfig;

To render the CSS, open your layout.tsx and wrap your application. The StyledComponentsRegistry component injects the server-rendered styles into the HTML via useServerInsertedHTML, so styled-components work with server-side rendering and the App Router.

It is the one export that depends on Next, so it ships from the cherry-styled-components/next subpath rather than the package root. Everything else imports from cherry-styled-components as usual:

app/layout.tsx

import { StyledComponentsRegistry } from "cherry-styled-components/next";
import { CherryThemeProvider, theme } from "cherry-styled-components";

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body>
        <StyledComponentsRegistry>
          <CherryThemeProvider theme={theme}>{children}</CherryThemeProvider>
        </StyledComponentsRegistry>
      </body>
    </html>
  );
}

Next.js requires these additional steps because it uses server-side rendering.