Global variables

Global variables set the colors, fonts, corner radius, shadows and spacing of the whole chat UI. Each one has a role, and many components use it. For example, --str-chat__text-primary colors message text, titles and most labels. Change it once and every component that uses it follows.

Global variables point at the palette. Component variables point at global variables, so a change here also reaches the components that build on it.

The variables fall into two groups:

• Theme: colors, typography, corner radius and shadows.
• Layout: spacing and sizes.

Overriding global variables

Set the light value on .str-chat and the dark value on .str-chat__theme-dark, in a CSS layer after the SDK's:

@layer stream, stream-overrides;
@import "stream-chat-react/dist/css/index.css" layer(stream);

@layer stream-overrides {
  .str-chat {
    --str-chat__accent-primary: #6d28d9;
    --str-chat__text-link: #6d28d9;
  }

  .str-chat__theme-dark {
    --str-chat__accent-primary: #a78bfa;
    --str-chat__text-link: #c4b5fd;
  }
}

Primary buttons, switches, checkboxes, mentions and the read status turn purple, and so do links. The user's own message bubbles stay blue: they use the brand scale, not the accent. To change them too, set the outgoing message variables.

Three things to know:

• Put overrides on .str-chat. The SDK declares every variable on .str-chat, so a value set on :root or on a wrapper element never reaches the UI.
• Put the dark rule after the light one. Both selectors have the same specificity, so the later rule wins. A value set only on .str-chat applies to both themes.
• Override on .str-chat, not on an element inside it. A variable that points at another one gets its value on .str-chat. For example, --str-chat__chat-text-incoming points at --str-chat__text-primary. Changing --str-chat__text-primary on an element inside .str-chat doesn't change --str-chat__chat-text-incoming there.

Reading the tables

• Light is the default value. When it points at another variable, the value that resolves to is in brackets.
• Dark is the value inside .str-chat__theme-dark. It shows only the resolved value when the variable points at the same variable as in the light theme, and "same" when nothing changes.
• The tables list the variables a built-in rule reads. The stylesheet declares a few more, such as --str-chat__accent-warning and --str-chat__border-utility-success, that no rule reads, so changing them has no effect.

Theme

Accent colors

Text colors

Background colors

Border colors

Focus outline

Every focusable element inside .str-chat draws this outline when the browser shows its focus, as with keyboard navigation.

Typography

Font family

The SDK doesn't load the Geist font. If your app doesn't load it either, text falls back to the system fonts in the stack.

Text styles

Each text style is a font shorthand, used as font: var(--str-chat__font-body-default). It combines a weight, a size and a line height from the tables below, with --str-chat__font-family.

Font sizes

Line heights

Font weights

Corner radius

Shadows

The shadows are layered box-shadow values. Each theme points them at its own elevation values.

Layout

Spacing

Sizes

Scale values

The spacing, radius, size and typography variables above point at these steps. The default theme uses only some of them; the rest are there for your own overrides.

Best Practices

• Use global variables for changes that should apply everywhere, such as the brand color or the font.
• Keep one source of truth for colors and typography, so your tokens don't drift apart.
• Change layout variables sparingly. Components are aligned to the spacing scale.
• Check contrast and spacing in both the light and dark themes after a change.
• Move to component variables only when a global change reaches too far.

The colors come from the generated light.scss and dark.scss. The text styles are in variables/fonts.scss, the shadows in variables/shadows.scss and the focus outline in base.scss.