setting-up-charcoal-styled

Setting up charcoal with styled-components

@charcoal-ui/styled exists for codebases already written in styled-components. Read the next section before wiring it in.

Choose this only for existing code

@charcoal-ui/styled is frozen at Design Token 1.0. Its source contains no reference to Token 2.0, and it receives only maintenance commits while @charcoal-ui/tailwind-config keeps gaining v2 features.

The package is not formally deprecated — only createTheme carries @deprecated. The problem is not that it is forbidden; it is that it cannot reach the current token generation.

It also drags in the component library: @charcoal-ui/styled peer-depends on @charcoal-ui/react, because useTheme, useThemeSetter, themeSelector, and SetThemeScript are re-exports whose implementations live there. You get that dependency even if you never render a charcoal component.

For a new project, or when you only want tokens, use setting-up-charcoal-css-variables instead.

Install

npm install @charcoal-ui/styled@^6 @charcoal-ui/theme@^6 @charcoal-ui/react@^6

Pin the major and keep every @charcoal-ui/* package on the same one. styled-components >=5.1.1 and react >=17.0.0 are peers.

Provider

Two independent mechanisms, both usually needed:

• ThemeProvider (styled-components) supplies the JS theme object so ${({ theme }) => theme.color.text1} resolves. The values are literal hex strings, not var().
• TokenInjector (@charcoal-ui/styled) emits --charcoal-color-* CSS variables at runtime via createGlobalStyle, for anything not going through styled-components.

import { ThemeProvider } from 'styled-components'
import {
  TokenInjector,
  addThemeUtils,
  useTheme,
  useThemeSetter,
  themeSelector,
} from '@charcoal-ui/styled'
import { light, dark } from '@charcoal-ui/theme'

const lightTheme = addThemeUtils(light)
const darkTheme = addThemeUtils(dark)

export function ThemeRoot({ children }: { children: React.ReactNode }) {
  const [mode] = useTheme()
  useThemeSetter()

  return (
    <ThemeProvider theme={mode === 'dark' ? darkTheme : lightTheme}>
      <TokenInjector
        theme={{ ':root': light, [themeSelector('dark')]: dark }}
        background="background1"
      />
      {children}
    </ThemeProvider>
  )
}