css.createTheme

View as Markdown

type CreateTheme = {
  [key: string]: {
    default: string;
    theme: string;
  };
};

export type createTheme = <const T extends CreateTheme>(themeSelector: CreateThemeSelector, rule: T) => CreateThemeReturnType<T>;
export const createTheme: createTheme;

createTheme defines scoped CSS variables for custom themes.
Since a unique hash is automatically prepended to the generated variable names, there is zero risk of name collisions with other themes or global CSS variables.

References between Plumeria themes are not supported: default and theme accept strings, not another theme member, and generated CSS variable names are content hashes that can change when the theme changes.

selector Patterns & Compiled CSS

createTheme supports class names, attribute selectors, and nesting-capable conditional at-rules (like @media, @container, @layer, @scope and @supports). Here are three common selector patterns and their compiled native CSS outputs:

1. Class-based Selector (`.dark`)

Excellent for toggling themes by adding a class to the root element.

import * as css from '@plumeria/core';

export const theme = css.createTheme('.dark', {
  text: {
    default: '#333',
    theme: '#eaeaea',
  },
});

Compiled CSS:

:where(:root) {
  --xvgqnxo9-text: #333;
}

.dark {
  --xvgqnxo9-text: #eaeaea;
}

2. Attribute-based Selector (`[data-theme="dark"]`)

Great for attribute-based theme setups (e.g. Next-Themes).

import * as css from '@plumeria/core';

export const theme = css.createTheme('[data-theme="dark"]', {
  text: {
    default: '#333',
    theme: '#eaeaea',
  },
});

Compiled CSS:

:where(:root) {
  --xipw25nr-text: #333;
}

[data-theme="dark"] {
  --xipw25nr-text: #eaeaea;
}

3. Media Query (`@media (prefers-color-scheme: dark)`)

Ideal for automatic system-level dark mode switching without any JavaScript.

import * as css from '@plumeria/core';

export const theme = css.createTheme('@media (prefers-color-scheme: dark)', {
  text: {
    default: '#333',
    theme: '#eaeaea',
  },
});

Compiled CSS:

:where(:root) {
  --xnof3ra0-text: #333;
}

@media (prefers-color-scheme: dark) {
  :where(:root) {
    --xnof3ra0-text: #eaeaea;
  }
}

Good to know

All APIs, including createTheme, are not compiled until the theme variable is actually used in a styling block.

css.createTheme

selector Patterns & Compiled CSS

1. Class-based Selector (.dark)

2. Attribute-based Selector ([data-theme="dark"])

3. Media Query (@media (prefers-color-scheme: dark))

On this page

1. Class-based Selector (`.dark`)

2. Attribute-based Selector (`[data-theme="dark"]`)

3. Media Query (`@media (prefers-color-scheme: dark)`)