lib/streamlit/.agents/skills/developing-with-streamlit/references/ccv2-theme-css-variables.md
--st-*)Streamlit injects a set of --st-* CSS custom properties into CCv2 components so your component can match the app’s active theme from within your component CSS (including when isolate_styles=True and you’re rendering inside a shadow root).
Recommendation: Prefer var(--st-…) over hard-coded colors and sizes. These variables automatically adapt to a user's current Streamlit theme (light/dark/custom), so most components do not need separate “dark mode vs light mode” styling.
--st-*)Use them like any CSS variable:
.card {
background: var(--st-secondary-background-color);
color: var(--st-text-color);
border: 1px solid var(--st-border-color);
border-radius: var(--st-base-radius);
}
.primaryButton {
background: var(--st-primary-color);
color: var(--st-background-color);
border-radius: var(--st-button-radius);
}
These variables originate from Streamlit’s theme object and are serialized into strings:
--st-primary-color: #ff4b4b).--st-base-font-weight: 400)."1" or "0" (e.g. --st-link-underline).--st-heading-font-sizes: 2.75rem,2.25rem,...).
",".null / undefined): become unset so consumers fall back to initial/inherited CSS behavior.--st-*)Use this section as your starting point. It covers what most components need most of the time.
| Intent | Variables |
|---|---|
| App/page background | --st-background-color |
| Panel/card background | --st-secondary-background-color |
| Body text | --st-text-color |
| Headings | --st-heading-color, --st-heading-font |
| Primary accent / emphasis | --st-primary-color |
| Links | --st-link-color, --st-link-underline |
| Borders / dividers | --st-border-color, --st-border-color-light |
| Widget outline borders | --st-widget-border-color |
| Corner radius | --st-base-radius, --st-button-radius |
| Code blocks | --st-code-background-color, --st-code-text-color, --st-code-font |
--st-background-color (page background)--st-secondary-background-color (panels, cards, containers)--st-text-color (default text)--st-heading-color (derived heading color)--st-primary-color (brand / accent)--st-link-color (link color)--st-link-underline (boolean serialized to "1" / "0")--st-border-color (default borders/dividers)--st-border-color-light (derived lighter border)--st-widget-border-color (widget borders)--st-base-radius--st-button-radius--st-code-background-color--st-code-text-color--st-font (body font)--st-heading-font--st-code-font--st-base-font-size--st-base-font-weight (number)Arrays (comma-joined):
--st-heading-font-sizes (array; typically 6 values for H1–H6)--st-heading-font-weights (array; typically 6 values for H1–H6)Per-level convenience variables:
--st-heading-font-size-1--st-heading-font-size-2--st-heading-font-size-3--st-heading-font-size-4--st-heading-font-size-5--st-heading-font-size-6--st-heading-font-weight-1 (number)--st-heading-font-weight-2 (number)--st-heading-font-weight-3 (number)--st-heading-font-weight-4 (number)--st-heading-font-weight-5 (number)--st-heading-font-weight-6 (number)--st-code-font-size--st-code-font-weight (number)--st-dataframe-border-color--st-dataframe-header-background-colorChart palette variables are arrays serialized as comma-joined strings:
--st-chart-categorical-colors (discrete series)--st-chart-sequential-colors (low → high)--st-chart-diverging-colors (negative ↔ positive around a midpoint)If you need the palette values in JS, split on commas:
export default function (component) {
const { parentElement } = component;
const host = parentElement.host ?? parentElement;
const raw = getComputedStyle(host)
.getPropertyValue('--st-chart-categorical-colors')
.trim();
const palette = raw ? raw.split(',') : [];
}
These are best for status UI (badges, alerts, validation messages), not for primary layout surfaces.
Each “family” typically comes in three variants:
--st-<name>-color--st-<name>-background-color--st-<name>-text-colorFamilies:
--st-red-color, --st-red-background-color, --st-red-text-color--st-orange-color, --st-orange-background-color, --st-orange-text-color--st-yellow-color, --st-yellow-background-color, --st-yellow-text-color--st-blue-color, --st-blue-background-color, --st-blue-text-color--st-green-color, --st-green-background-color, --st-green-text-color--st-violet-color, --st-violet-background-color, --st-violet-text-color--st-gray-color, --st-gray-background-color, --st-gray-text-color--st-background-color--st-base-font-size--st-base-font-weight--st-base-radius--st-blue-background-color--st-blue-color--st-blue-text-color--st-border-color--st-border-color-light--st-button-radius--st-chart-categorical-colors--st-chart-diverging-colors--st-chart-sequential-colors--st-code-background-color--st-code-font--st-code-font-size--st-code-font-weight--st-code-text-color--st-dataframe-border-color--st-dataframe-header-background-color--st-font--st-gray-background-color--st-gray-color--st-gray-text-color--st-green-background-color--st-green-color--st-green-text-color--st-heading-color--st-heading-font--st-heading-font-size-1--st-heading-font-size-2--st-heading-font-size-3--st-heading-font-size-4--st-heading-font-size-5--st-heading-font-size-6--st-heading-font-sizes--st-heading-font-weight-1--st-heading-font-weight-2--st-heading-font-weight-3--st-heading-font-weight-4--st-heading-font-weight-5--st-heading-font-weight-6--st-heading-font-weights--st-link-color--st-link-underline--st-orange-background-color--st-orange-color--st-orange-text-color--st-primary-color--st-red-background-color--st-red-color--st-red-text-color--st-secondary-background-color--st-text-color--st-violet-background-color--st-violet-color--st-violet-text-color--st-widget-border-color--st-yellow-background-color--st-yellow-color--st-yellow-text-color