Component variables

Component variables change one part of the UI without touching the rest. For example, --str-chat__chat-bg-outgoing is the background of the messages the user sent. It points at --str-chat__brand-100. Override it and only those bubbles change; buttons and links keep the brand color.

Most component variables point at a global variable, so they follow your global changes until you override them. Color variables get their dark values the same way as global ones.

Overriding component variables

Set them on .str-chat, 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__chat-bg-outgoing: #1e3a8a;
    --str-chat__chat-border-outgoing: #1e3a8a;
    --str-chat__chat-text-outgoing: #ffffff;
    --str-chat__chat-bg-attachment-outgoing: #1d4ed8;
  }
}

To set a different value for the dark theme, add a .str-chat__theme-dark rule after this one. The rules for global variables apply here too: see Overriding global variables.

Where the SDK declares a variable decides where you override it:

• On .str-chat. Most variables. Override them on .str-chat.
• On the component's own element. The gallery declares its variables on .str-chat .str-chat__gallery, the attachment sizes are on .str-chat__attachment-list, and channel details declare theirs on .str-chat__section-navigator__navigation-overlay. Override them on the same selector.
• Nowhere. A few variables are read with a fallback and never declared: notifications, the channel details overlay and the AI components. Set them on any element above the component, :root included.

Some variables aren't listed because they aren't meant to be overridden. The components set some at runtime, such as image dimensions, playback and poll vote progress, and waveform bar heights. Each message also sets internal helpers, such as --chat-bg and --chat-text, from the incoming and outgoing variables in the Message tables. Override the incoming and outgoing variables, not the helpers.

The tables list the variables a built-in rule reads, with the same columns as the global variables tables.

Components

Avatar

Stylesheet: Avatar.scss

The theme also declares --str-chat__avatar-palette-bg-2 to -5 and --str-chat__avatar-palette-text-2 to -5. No rule reads them: every avatar uses the first palette entry.

Badge

Stylesheet: Badge.scss

Button

Stylesheet: Button.scss

Colors by variant. The -on-dark variables are used by buttons drawn on an inverse surface.

Shape and size. The visual-height variables size a few elements to match a button.

Form controls

Used by form fields, the attachment preview remove button, audio playback, video thumbnails and the reaction filters.

Switch fields:

Message

Stylesheets: Message.scss and components/Attachment/styling/

Bubble colors. Each pair sets messages from others (-incoming) and the user's own messages (-outgoing).

Size and shape:

--str-chat__attachment-max-width and --str-chat__video-height are declared on .str-chat__attachment-list, so override them there. In a message that is one attachment without text, --str-chat__attachment-max-width is --str-chat__message-max-width.

Reactions

Stylesheet: components/Reactions/styling/

Message composer

Stylesheets: components/MessageComposer/styling/ and components/Form/styling/

Two of these have no working default. --str-chat__attachment-preview-media-upload-error-overlay-background-color points at --background-core-overlay, and --str-chat__attachment-selector-button-icon-color points at --button-style-outline-text. The SDK declares neither, so both stay unset until you give them a value.

Channel header

Stylesheet: ChannelHeader.scss

Channel list

Stylesheet: ChannelList.scss

Thread list

Stylesheet: ThreadList.scss

The rule multiplies --str-chat__thread-list-transition-offset by -1px, so only a plain number, such as 8, works. The default, 8px, makes the transform invalid, and the list doesn't slide.

ChatView

Stylesheet: ChatView.scss

Context menu

Stylesheet: ContextMenu.scss

Modal

Stylesheet: Modal.scss

The gallery modal sets --str-chat__modal-overlay-backdrop-filter to none.

Gallery

Stylesheet: Gallery.scss

Declared on .str-chat .str-chat__gallery, with the dark values on .str-chat.str-chat__theme-dark .str-chat__gallery.

Notification

Stylesheet: Notification.scss

Read with a fallback, never declared.

Tooltip

Stylesheet: Tooltip.scss

Channel details

Stylesheet: SectionNavigator.scss, part of channel-detail.css

Declared on .str-chat__section-navigator__navigation-overlay:

Read with a fallback, never declared:

AI components

Stylesheet: _tokens.scss, part of ai-components.css

The SDK never declares the --str-chat__ai-* variables. Each rule reads your value first. Without one, it uses the global variable inside .str-chat, which follows the light and dark themes, and a fixed color outside .str-chat.

The code block colors have no global variable behind them, only a fixed fallback: --str-chat__ai-syntax-text, --str-chat__ai-syntax-selection-bg, --str-chat__ai-syntax-comment, --str-chat__ai-syntax-punctuation, --str-chat__ai-syntax-number, --str-chat__ai-syntax-keyword, --str-chat__ai-syntax-tag, --str-chat__ai-syntax-string, --str-chat__ai-syntax-function, --str-chat__ai-syntax-cyan, --str-chat__ai-syntax-error, --str-chat__ai-syntax-whitespace.

Best Practices

• Use component variables for a change in one place that shouldn't ripple through the UI.
• Start with color variables before layout variables, so component spacing stays intact.
• Keep track of your overrides per component, to avoid duplicated or conflicting values.
• Prefer variables over CSS overrides of SDK class names. Variables are more likely to survive an upgrade.
• Re-test the busy components, such as the message, the composer and the channel list, after a change.