Global variables

Info:

This part of the documentation refers to the new version of the theming and customization system which won't work with the old system, please refer to the theme-v2 documentation to learn more about the new system or CSS and Theming if you need documentation for the old system (also known as v1 or version 1).

CSS variables are the easiest way to customize the theme. The variables are organized into two layers:

Global
Component

This page contains information about the global variables.

Global variables can be grouped into the following categories:

Theme: colors, typography and border radiuses
Layout: spacing (padding and margin) and sizing

You can read about each category in detail in the tables below.

Theme variables

Colors

Name Value(s) Description Used in

--str-chat__primary-color

`.str-chat,.str-chat__theme-light`
`var(--str-chat__blue500)`
`.str-chat__theme-dark`
`var(--str-chat__blue400)`

Used for emphasis, brands can inject their main color using this variable

AttachmentList, AttachmentPreviewList, Autocomplete, Avatar, ChannelSearch, CircleFAButton, CTAButton, EditMessageForm, LinkPreview, Message, MessageBounceOptions, MessageInput, MessageReactions, MessageNotification

--str-chat__primary-overlay-color

`.str-chat,.str-chat__theme-light`
`rgba(0, 95, 255, 0.6)`
`.str-chat__theme-dark`
`rgba(51, 126, 255, 0.6)`

Used for emphasised overlays - color of --str-chat__primary-color with alpha channel

MessageInput

--str-chat__primary-color-low-emphasis

`.str-chat,.str-chat__theme-light`
`var(--str-chat__blue300)`
`.str-chat__theme-dark`
`var(--str-chat__blue700)`

Used for emphasis, brands can inject their main color using this variable, it has less emphasis than primary color

MessageReactionsSelector

--str-chat__active-primary-color

`.str-chat,.str-chat__theme-light`
`var(--str-chat__blue600)`
`.str-chat__theme-dark`
`var(--str-chat__blue600)`

Used to indicate that a UI element with primary color is in an active state

CTAButton

--str-chat__on-primary-color

`.str-chat,.str-chat__theme-light`
`var(--str-chat__grey50)`
`.str-chat__theme-dark`
`var(--str-chat__grey50)`

If the primary color is used as a background, text/icons are displayed in this color

Avatar, CTAButton, Message, MessageInput, MessageNotification

--str-chat__background-color

`.str-chat,.str-chat__theme-light`
`var(--str-chat__grey50)`
`.str-chat__theme-dark`
`var(--str-chat__grey950)`

Used as a background color for the main chat UI components

Channel, ChannelSearch, MessageList, VirtualizedMessageList

--str-chat__secondary-background-color

`.str-chat,.str-chat__theme-light`
`var(--str-chat__grey50)`
`.str-chat__theme-dark`
`var(--str-chat__grey900)`

Used as a background color for the main chat UI components

AttachmentList, Autocomplete, ChannelHeader, ChannelList, ChannelSearch, CircleFAButton, Message, MessageActionsBox, MessageInput, MessageReactionsSelector, Modal, Thread, Tooltip

--str-chat__primary-surface-color

`.str-chat,.str-chat__theme-light`
`var(--str-chat__blue100)`
`.str-chat__theme-dark`
`var(--str-chat__blue900)`

Used as a background color to give emphasis, but less vibrant than the primary color

Message, MessageReactionsSelector

--str-chat__primary-surface-color-low-emphasis

`.str-chat,.str-chat__theme-light`
`var(--str-chat__blue50)`
`.str-chat__theme-dark`
`var(--str-chat__blue950)`

Used as a background color to give emphasis, but less vibrant than the primary surface color

MessageReactions

--str-chat__surface-color

`.str-chat,.str-chat__theme-light`
`var(--str-chat__grey300)`
`.str-chat__theme-dark`
`var(--str-chat__grey700)`

A neutral color used to give emphasis to different surfaces

AttachmentList, AttachmentPreviewList, Autocomplete, ChannelList, ChannelPreview, ChannelSearch, CircleFAButton, MessageInput, MessageList, Thread

--str-chat__secondary-surface-color

`.str-chat,.str-chat__theme-light`
`var(--str-chat__grey200)`
`.str-chat__theme-dark`
`var(--str-chat__grey800)`

A neutral color used to give emphasis to different surfaces

AttachmentList, BaseImage, ChannelPreview, ChannelSearch, Message, MessageActionsBox

--str-chat__tertiary-surface-color

`.str-chat,.str-chat__theme-light`
`var(--str-chat__grey100)`
`.str-chat__theme-dark`
`var(--str-chat__grey900)`

A neutral color used to give emphasis to different surfaces

Message, MessageReactions

--str-chat__text-color

`.str-chat,.str-chat__theme-light`
`var(--str-chat__grey950)`
`.str-chat__theme-dark`
`var(--str-chat__grey50)`

The main color used for texts/icons

AttachmentList, AttachmentPreviewList, Autocomplete, BaseImage, Channel, ChannelList, ChannelPreview, ChannelSearch, ImageCarousel, Message, MessageActionsBox, MessageInput, MessageList, VirtualizedMessageList, MessageReactions, MessageReactionsSelector, Modal, Thread, Tooltip, TypingIndicator

--str-chat__text-low-emphasis-color

`.str-chat,.str-chat__theme-light`
`var(--str-chat__grey500)`
`.str-chat__theme-dark`
`var(--str-chat__grey500)`

Used for texts/icons that need less emphasis

AttachmentList, AttachmentPreviewList, Autocomplete, Channel, ChannelHeader, ChannelPreview, ChannelSearch, EditMessageForm, LinkPreview, Message, MessageInput, MessageList, Modal, Thread, TypingIndicator

--str-chat__disabled-color

`.str-chat,.str-chat__theme-light`
`var(--str-chat__grey400)`
`.str-chat__theme-dark`
`var(--str-chat__grey600)`

Used for displaying disabled UI elements (typically buttons)

AttachmentList, BaseImage, Channel, ChannelList, ChannelPreview, ChannelSearch, CTAButton, Message, MessageInput

--str-chat__on-disabled-color

`.str-chat,.str-chat__theme-light`
`var(--str-chat__grey50)`
`.str-chat__theme-dark`
`var(--str-chat__grey50)`

Used for text/icon colors if disabled color is used as a background color

CTAButton, MessageInput, Modal

--str-chat__danger-color

`.str-chat,.str-chat__theme-light`
`var(--str-chat__red400)`
`.str-chat__theme-dark`
`var(--str-chat__red600)`

Used for error messages, and destructive actions

Message

--str-chat__message-highlight-color

`.str-chat,.str-chat__theme-light`
`var(--str-chat__yellow100)`
`.str-chat__theme-dark`
`var(--str-chat__yellow900)`

The background color used to highlight a message when jumping to a message. Only available in React SDK.

Message

--str-chat__unread-badge-color

`.str-chat,.str-chat__theme-light`
`var(--str-chat__red400)`
`.str-chat__theme-dark`
`var(--str-chat__red400)`

Used for displaying the unread badge

ChannelPreview

--str-chat__on-unread-badge-color

`.str-chat,.str-chat__theme-light`
`var(--str-chat__grey50)`
`.str-chat__theme-dark`
`var(--str-chat__grey50)`

Used for text/icon colors if unread badge color is used as a background color

ChannelPreview

--str-chat__overlay-color

`.str-chat,.str-chat__theme-light`
`rgba(252, 252, 252, 0.9)`
`.str-chat__theme-dark`
`rgba(0, 0, 0, 0.7)`

The background color used for overlays

AttachmentPreviewList, TypingIndicator

--str-chat__secondary-overlay-color

`.str-chat,.str-chat__theme-light`
`rgba(0, 0, 0, 0.2)`
`.str-chat__theme-dark`
`rgba(0, 0, 0, 0.4)`

The background color used for subtle overlays

AttachmentList, AttachmentPreviewList, Modal

--str-chat__secondary-overlay-text-color

`.str-chat,.str-chat__theme-light`
`var(--str-chat__grey50)`
`.str-chat__theme-dark`
`var(--str-chat__grey50)`

The text/icon color used on subtle overlays

AttachmentList, AttachmentPreviewList

--str-chat__opaque-surface-background-color

`.str-chat,.str-chat__theme-light`
`rgba(0, 0, 0, 0.8)`
`.str-chat__theme-dark`
`rgba(250, 250, 250, 0.85)`

The background color used for opaque surfaces

Notification

--str-chat__opaque-surface-text-color

`.str-chat,.str-chat__theme-light`
`var(--str-chat__grey50)`
`.str-chat__theme-dark`
`var(--str-chat__grey900)`

The text color used on opaque surfaces

Notification

--str-chat__box-shadow-color

`.str-chat,.str-chat__theme-light`
`rgba(0, 0, 0, 0.18)`
`.str-chat__theme-dark`
`rgba(0, 0, 0, 0.8)`

If a component has a box shadow applied to it, this will be the color used for the shadow

ChannelSearch, MessageActionsBox, MessageReactionsSelector, Notification, Tooltip

--str-chat__info-color

`.str-chat,.str-chat__theme-light`
`var(--str-chat__green500)`
`.str-chat__theme-dark`
`var(--str-chat__green500)`

Used for online indicator and success messages

Avatar

Typography

Name Value(s) Description Used in

--str-chat__font-family

`.str-chat`
`-apple-system , BlinkMacSystemFont , Segoe UI , Roboto , Oxygen-Sans , Ubuntu , Cantarell , Helvetica Neue , sans-serif`

The font used in the chat, by default, we use preinstalled OS fonts

Autocomplete

--str-chat__caption-text

`.str-chat`
`0.75 rem/1rem var(--str-chat__font-family)`

The font used for caption texts

LinkPreview, Message, MessageList, MessageReactions, MessageNotification, Tooltip

--str-chat__caption-medium-text

`.str-chat`
`500 0.75 rem/1rem var(--str-chat__font-family)`

The font used for caption texts with emphasize

Message

--str-chat__caption-strong-text

`.str-chat`
`700 0.75 rem/1rem var(--str-chat__font-family)`

The font used for caption texts with emphasize

Message

--str-chat__body-text

`.str-chat`
`0.875 rem/1rem var(--str-chat__font-family)`

The font used for body texts

AttachmentList, ChannelHeader, ChannelPreview, Message, Thread

--str-chat__body-medium-text

`.str-chat`
`500 0.875 rem/1rem var(--str-chat__font-family)`

The font used for body texts with emphasize

AttachmentList, EditMessageForm, LinkPreview, Message, MessageBounceOptions

--str-chat__body2-text

`.str-chat`
`0.9375 rem/1rem var(--str-chat__font-family)`

The font used for body texts

Message

--str-chat__body2-medium-text

`.str-chat`
`500 0.9375 rem/1rem var(--str-chat__font-family)`

The font used for body texts with emphasize

Message

--str-chat__subtitle-text

`.str-chat`
`1 rem/1.25rem var(--str-chat__font-family)`

The font used for subtitle texts

Autocomplete, ChannelSearch, CTAButton, MessageActionsBox, MessageInput, MessageList, VirtualizedMessageList, MessageReactions, Notification

--str-chat__subtitle-medium-text

`.str-chat`
`500 1 rem/1.25rem var(--str-chat__font-family)`

The font used for subtitle texts with emphasize

AttachmentList, AttachmentPreviewList, ChannelHeader, ChannelPreview, ChannelSearch, MessageInput, Thread

--str-chat__subtitle2-text

`.str-chat`
`1.25 rem/1.5rem var(--str-chat__font-family)`

The font used for subtitle texts

Autocomplete

--str-chat__subtitle2-medium-text

`.str-chat`
`500 1.25 rem/1.5rem var(--str-chat__font-family)`

The font used for subtitle texts with emphasize

ChannelSearch

--str-chat__headline-text

`.str-chat`
`1.5 rem/1.5rem var(--str-chat__font-family)`

The font used for headline texts

Channel, ChannelList

--str-chat__headline2-text

`.str-chat`
`1.8 rem/1.8rem var(--str-chat__font-family)`

The font used for headline texts

AttachmentList

Radius

Name Value(s) Description Used in

--str-chat__border-radius-xs

`.str-chat`
`8px`

Border radius used for slightly rounded elements

Autocomplete, Channel, ChannelPreview, CTAButton, MessageReactions, Tooltip

--str-chat__border-radius-sm

`.str-chat`
`14px`

Border radius used for slightly rounded elements

AttachmentPreviewList, MessageActionsBox, Modal, Notification

--str-chat__border-radius-md

`.str-chat`
`18px`

Border radius used for rounded elements

AttachmentPreviewList, Message, MessageInput, MessageReactionsSelector

--str-chat__border-radius-lg

`.str-chat`
`20px`

Border radius used for rounded elements

ChannelSearch

--str-chat__border-radius-circle

`.str-chat`
`999px`

Border radius used for circular elements

AttachmentList, AttachmentPreviewList, Avatar, ChannelPreview, CircleFAButton, Message, MessageInput, MessageReactionsSelector, Modal

All global theme variables are defined in: https://github.com/GetStream/stream-chat-css/tree/v4.6.1/src/v2/styles/_global-theme-variables.scss

Layout variables

Spacing

Name Value(s) Description

--str-chat__spacing-px

`.str-chat`
`1px`

Used for elements where sizing is necessary (such as icons, avatar), you can use this variable to scale those elements

--str-chat__spacing-0_5

`.str-chat`
`0.125rem`

Used for margins and paddings

--str-chat__spacing-1

`.str-chat`
`0.25rem`

Used for margins and paddings

--str-chat__spacing-1_5

`.str-chat`
`0.375rem`

Used for margins and paddings

--str-chat__spacing-2

`.str-chat`
`0.5rem`

Used for margins and paddings

--str-chat__spacing-2_5

`.str-chat`
`0.625rem`

Used for margins and paddings

--str-chat__spacing-3

`.str-chat`
`0.75rem`

Used for margins and paddings

--str-chat__spacing-3_5

`.str-chat`
`0.875rem`

Used for margins and paddings

--str-chat__spacing-4

`.str-chat`
`1rem`

Used for margins and paddings

--str-chat__spacing-5

`.str-chat`
`1.25rem`

Used for margins and paddings

--str-chat__spacing-6

`.str-chat`
`1.5rem`

Used for margins and paddings

--str-chat__spacing-7

`.str-chat`
`1.75rem`

Used for margins and paddings

--str-chat__spacing-8

`.str-chat`
`2rem`

Used for margins and paddings

--str-chat__spacing-9

`.str-chat`
`2.25rem`

Used for margins and paddings

--str-chat__spacing-10

`.str-chat`
`2.5rem`

Used for margins and paddings

--str-chat__spacing-11

`.str-chat`
`2.75rem`

Used for margins and paddings

--str-chat__spacing-12

`.str-chat`
`3rem`

Used for margins and paddings

--str-chat__spacing-14

`.str-chat`
`3.5rem`

Used for margins and paddings

--str-chat__spacing-16

`.str-chat`
`4rem`

Used for margins and paddings

Others

Name Value(s) Description

--str-chat__theme-version

`:root`
`2`

The theme version being used, 1 or 2. Used internally by SDKs

All global layout variables are defined in: https://github.com/GetStream/stream-chat-css/tree/v4.6.1/src/v2/styles/_global-layout-variables.scss

If you find that these variables are too high-level and you need more granular control, you also have the option to provide component layer overrides.