Skip to content
🚀 MUI X v6 is out! Discover what's new and get started now!
Edit this page

Theme colors

Learn about the default theme's color palette and how to customize it.

Default tokens

The table below lists all the default tokens and their values in light and dark color schemes. Some tokens reuse values from other tokens using the var(--*) syntax.

Copied

Token

Light

Dark

Channel tokens

The default tokens ending with Channel are automatically generated for each palette. These tokens are useful for creating translucent colors (rgba).

  • lightChannel: is generated from the palette's 200 token.
  • mainChannel: is generated from the palette's 500 token.
  • darkChannel: is generated from the palette's 800 token.

The example usage is:

<span class="token keyword">import</span> Typography <span class="token keyword">from</span> <span class="token string">'@mui/joy/Typography'</span><span class="token punctuation">;</span>

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Typography</span></span>
  <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token parameter">theme</span> <span class="token operator">=></span> <span class="token punctuation">(</span><span class="token punctuation">{</span>
    <span class="token literal-property property">color</span><span class="token operator">:</span> <span class="token template-string"><span class="token template-punctuation string">`</span><span class="token string">rgba(</span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>theme<span class="token punctuation">.</span>vars<span class="token punctuation">.</span>palette<span class="token punctuation">.</span>primary<span class="token punctuation">.</span>mainChannel<span class="token interpolation-punctuation punctuation">}</span></span><span class="token string"> / 0.72)</span><span class="token template-punctuation string">`</span></span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">}</span></span>
<span class="token punctuation">></span></span>

Global variant tokens

By default, Joy UI has four built-in global variants tokens: plain, outlined, soft, and solid.

The global variant token is composed of three parts, in the format of variant type | state | CSS property.

For example:

  • solidBg refers to the solid variant's background color in its initial state.
  • outlinedHoverBorder refers to the outlined variant's border color in its hover state.

There are six palettes (primary, neutral, danger, info, success, and warning) that contain the global variant tokens as listed in the table above.

Customizing the default palette

For each color scheme, the default colors are grouped within the palette node.

For example, the snippet below customizes the primary palette in dark mode:

<span class="token keyword">import</span> <span class="token punctuation">{</span> extendTheme <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/joy/styles'</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">extendTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">colorSchemes</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">dark</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">palette</span><span class="token operator">:</span> <span class="token punctuation">{</span>
        <span class="token literal-property property">primary</span><span class="token operator">:</span> <span class="token punctuation">{</span>
          <span class="token number">50</span><span class="token operator">:</span> <span class="token string">'#C0CCD9'</span><span class="token punctuation">,</span>
          <span class="token number">100</span><span class="token operator">:</span> <span class="token string">'#A5B8CF'</span><span class="token punctuation">,</span>
          <span class="token number">200</span><span class="token operator">:</span> <span class="token string">'#6A96CA'</span><span class="token punctuation">,</span>
          <span class="token number">300</span><span class="token operator">:</span> <span class="token string">'#4886D0'</span><span class="token punctuation">,</span>
          <span class="token number">400</span><span class="token operator">:</span> <span class="token string">'#2178DD'</span><span class="token punctuation">,</span>
          <span class="token number">500</span><span class="token operator">:</span> <span class="token string">'#096BDE'</span><span class="token punctuation">,</span>
          <span class="token number">600</span><span class="token operator">:</span> <span class="token string">'#1B62B5'</span><span class="token punctuation">,</span>
          <span class="token number">700</span><span class="token operator">:</span> <span class="token string">'#265995'</span><span class="token punctuation">,</span>
          <span class="token number">800</span><span class="token operator">:</span> <span class="token string">'#2F4968'</span><span class="token punctuation">,</span>
          <span class="token number">900</span><span class="token operator">:</span> <span class="token string">'#2F3C4C'</span><span class="token punctuation">,</span>
        <span class="token punctuation">}</span><span class="token punctuation">,</span>
      <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token comment">// Then, pass it to `&lt;CssVarsProvider theme={theme}>`.</span>

Customizing global variant tokens

We recommend using the Button component as a jumping-off point when customizing the global variants, because it gives you access to more of the interactive variants available than some other components.

As an example, let's customize Joy UI's Button so to match the style of Bootstrap:

  • Bootstrap's default buttons are comparable to Joy UI's solid variant.
  • Bootstrap's secondary variant uses a grey color, similar to Joy UI's neutral.
  • Bootstrap's btn-light is similar to Joy UI's button using the soft variant and neutral color palette.
  • Joy UI's defaults don't include anything similar to Bootstrap's btn-dark.
    • We can recreate it using one of the three main customization approaches.

Removing the default tokens

To remove any default token, use undefined as a value. This removes it from the theme object and prevents the corresponding CSS variable from being generated.

For example, all default global variant tokens comes with styles for the :active pseudo class. Here's how you'd remove it from the solid variant.

<span class="token comment">// ⚠️ If the value is `undefined`, it should be `undefined` for all color schemes.</span>
<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">extendTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">colorSchemes</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">light</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">palette</span><span class="token operator">:</span> <span class="token punctuation">{</span>
        <span class="token literal-property property">primary</span><span class="token operator">:</span> <span class="token punctuation">{</span>
          <span class="token literal-property property">solidActiveBg</span><span class="token operator">:</span> <span class="token keyword">undefined</span><span class="token punctuation">,</span>
        <span class="token punctuation">}</span><span class="token punctuation">,</span>
      <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token literal-property property">dark</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">palette</span><span class="token operator">:</span> <span class="token punctuation">{</span>
        <span class="token literal-property property">primary</span><span class="token operator">:</span> <span class="token punctuation">{</span>
          <span class="token literal-property property">solidActiveBg</span><span class="token operator">:</span> <span class="token keyword">undefined</span><span class="token punctuation">,</span>
        <span class="token punctuation">}</span><span class="token punctuation">,</span>
      <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

Adding more colors

Any custom tokens that you add to theme are available for use with both the styled and sx APIs.

<span class="token function">extendTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">colorSchemes</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">light</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">palette</span><span class="token operator">:</span> <span class="token punctuation">{</span>
        <span class="token comment">// Example of new color tokens.</span>
        <span class="token comment">// We recommend to limit them to 3 levels deep－in this case:</span>
        <span class="token comment">// `palette.gradient.primary`.</span>
        <span class="token literal-property property">gradient</span><span class="token operator">:</span> <span class="token punctuation">{</span>
          <span class="token literal-property property">primary</span><span class="token operator">:</span> <span class="token string">'linear-gradient(to top, var(--joy-palette-primary-main), #000)'</span><span class="token punctuation">,</span>
        <span class="token punctuation">}</span><span class="token punctuation">,</span>
      <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token comment">// `sx` prop usage example:</span>
<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Button</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token function-variable function">background</span><span class="token operator">:</span> <span class="token punctuation">(</span><span class="token parameter">theme</span><span class="token punctuation">)</span> <span class="token operator">=></span> theme<span class="token punctuation">.</span>vars<span class="token punctuation">.</span>palette<span class="token punctuation">.</span>gradient<span class="token punctuation">.</span>primary <span class="token punctuation">}</span><span class="token punctuation">}</span></span> <span class="token punctuation">/></span></span><span class="token punctuation">;</span>

TypeScript

When working in TypeScript, you must augment the theme's Palette interface to include the new tokens.

<span class="token comment">// You can put this to any file that's included in your tsconfig</span>
declare module <span class="token string">'@mui/joy/styles'</span> <span class="token punctuation">{</span>
  <span class="token keyword">interface</span> <span class="token class-name">Palette</span> <span class="token punctuation">{</span>
    gradient<span class="token operator">:</span> <span class="token punctuation">{</span>
      primary<span class="token operator">:</span> string<span class="token punctuation">;</span>
    <span class="token punctuation">}</span><span class="token punctuation">;</span>
  <span class="token punctuation">}</span>
<span class="token punctuation">}</span>

Adding more palettes

You can add your own palettes to your app's theme to pass custom color schemes to any components that accept the color prop.

The snippet below adds a custom secondary palette to the theme.

<span class="token keyword">import</span> <span class="token punctuation">{</span> extendTheme <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/joy/styles'</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">extendTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">colorSchemes</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">light</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">palette</span><span class="token operator">:</span> <span class="token punctuation">{</span>
        <span class="token literal-property property">secondary</span><span class="token operator">:</span> <span class="token punctuation">{</span>
          <span class="token comment">// Credit:</span>
          <span class="token comment">// https://github.com/tailwindlabs/tailwindcss/blob/master/src/public/colors.js</span>
          <span class="token number">50</span><span class="token operator">:</span> <span class="token string">'#fdf2f8'</span><span class="token punctuation">,</span>
          <span class="token number">100</span><span class="token operator">:</span> <span class="token string">'#fce7f3'</span><span class="token punctuation">,</span>
          <span class="token number">200</span><span class="token operator">:</span> <span class="token string">'#fbcfe8'</span><span class="token punctuation">,</span>
          <span class="token number">300</span><span class="token operator">:</span> <span class="token string">'#f9a8d4'</span><span class="token punctuation">,</span>
          <span class="token number">400</span><span class="token operator">:</span> <span class="token string">'#f472b6'</span><span class="token punctuation">,</span>
          <span class="token number">500</span><span class="token operator">:</span> <span class="token string">'#ec4899'</span><span class="token punctuation">,</span>
          <span class="token number">600</span><span class="token operator">:</span> <span class="token string">'#db2777'</span><span class="token punctuation">,</span>
          <span class="token number">700</span><span class="token operator">:</span> <span class="token string">'#be185d'</span><span class="token punctuation">,</span>
          <span class="token number">800</span><span class="token operator">:</span> <span class="token string">'#9d174d'</span><span class="token punctuation">,</span>
          <span class="token number">900</span><span class="token operator">:</span> <span class="token string">'#831843'</span><span class="token punctuation">,</span>
          <span class="token comment">// Adjust the global variant tokens as you'd like.</span>
          <span class="token comment">// The tokens should be the same for all color schemes.</span>
          <span class="token literal-property property">solidBg</span><span class="token operator">:</span> <span class="token string">'var(--joy-palette-secondary-400)'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">solidActiveBg</span><span class="token operator">:</span> <span class="token string">'var(--joy-palette-secondary-500)'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">outlinedBorder</span><span class="token operator">:</span> <span class="token string">'var(--joy-palette-secondary-500)'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">outlinedColor</span><span class="token operator">:</span> <span class="token string">'var(--joy-palette-secondary-700)'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">outlinedActiveBg</span><span class="token operator">:</span> <span class="token string">'var(--joy-palette-secondary-100)'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">softColor</span><span class="token operator">:</span> <span class="token string">'var(--joy-palette-secondary-800)'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">softBg</span><span class="token operator">:</span> <span class="token string">'var(--joy-palette-secondary-200)'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">softActiveBg</span><span class="token operator">:</span> <span class="token string">'var(--joy-palette-secondary-300)'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">plainColor</span><span class="token operator">:</span> <span class="token string">'var(--joy-palette-secondary-700)'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">plainActiveBg</span><span class="token operator">:</span> <span class="token string">'var(--joy-palette-secondary-100)'</span><span class="token punctuation">,</span>
        <span class="token punctuation">}</span><span class="token punctuation">,</span>
      <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token literal-property property">dark</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">palette</span><span class="token operator">:</span> <span class="token punctuation">{</span>
        <span class="token literal-property property">secondary</span><span class="token operator">:</span> <span class="token punctuation">{</span>
          <span class="token comment">// Credit:</span>
          <span class="token comment">// https://github.com/tailwindlabs/tailwindcss/blob/master/src/public/colors.js</span>
          <span class="token number">50</span><span class="token operator">:</span> <span class="token string">'#fdf2f8'</span><span class="token punctuation">,</span>
          <span class="token number">100</span><span class="token operator">:</span> <span class="token string">'#fce7f3'</span><span class="token punctuation">,</span>
          <span class="token number">200</span><span class="token operator">:</span> <span class="token string">'#fbcfe8'</span><span class="token punctuation">,</span>
          <span class="token number">300</span><span class="token operator">:</span> <span class="token string">'#f9a8d4'</span><span class="token punctuation">,</span>
          <span class="token number">400</span><span class="token operator">:</span> <span class="token string">'#f472b6'</span><span class="token punctuation">,</span>
          <span class="token number">500</span><span class="token operator">:</span> <span class="token string">'#ec4899'</span><span class="token punctuation">,</span>
          <span class="token number">600</span><span class="token operator">:</span> <span class="token string">'#db2777'</span><span class="token punctuation">,</span>
          <span class="token number">700</span><span class="token operator">:</span> <span class="token string">'#be185d'</span><span class="token punctuation">,</span>
          <span class="token number">800</span><span class="token operator">:</span> <span class="token string">'#9d174d'</span><span class="token punctuation">,</span>
          <span class="token number">900</span><span class="token operator">:</span> <span class="token string">'#831843'</span><span class="token punctuation">,</span>
          <span class="token comment">// Adjust the global variant tokens as you'd like.</span>
          <span class="token comment">// The tokens should be the same for all color schemes.</span>
          <span class="token literal-property property">solidBg</span><span class="token operator">:</span> <span class="token string">'var(--joy-palette-secondary-400)'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">solidActiveBg</span><span class="token operator">:</span> <span class="token string">'var(--joy-palette-secondary-500)'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">outlinedBorder</span><span class="token operator">:</span> <span class="token string">'var(--joy-palette-secondary-700)'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">outlinedColor</span><span class="token operator">:</span> <span class="token string">'var(--joy-palette-secondary-600)'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">outlinedActiveBg</span><span class="token operator">:</span> <span class="token string">'var(--joy-palette-secondary-900)'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">softColor</span><span class="token operator">:</span> <span class="token string">'var(--joy-palette-secondary-500)'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">softBg</span><span class="token operator">:</span> <span class="token string">'var(--joy-palette-secondary-900)'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">softActiveBg</span><span class="token operator">:</span> <span class="token string">'var(--joy-palette-secondary-800)'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">plainColor</span><span class="token operator">:</span> <span class="token string">'var(--joy-palette-secondary-500)'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">plainActiveBg</span><span class="token operator">:</span> <span class="token string">'var(--joy-palette-secondary-900)'</span><span class="token punctuation">,</span>
        <span class="token punctuation">}</span><span class="token punctuation">,</span>
      <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token comment">// Then, pass it to `&lt;CssVarsProvider theme={theme}>`.</span>

Then, you will be able to use secondary color on Joy UI components:

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Button</span></span> <span class="token attr-name">color</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>secondary<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">IconButton</span></span> <span class="token attr-name">variant</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>outlined<span class="token punctuation">"</span></span> <span class="token attr-name">color</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>secondary<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Chip</span></span> <span class="token attr-name">variant</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>soft<span class="token punctuation">"</span></span> <span class="token attr-name">color</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>secondary<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>

TypeScript

When working in TypeScript, you must augment the theme's interfaces to include the new palette.

<span class="token comment">// You can put this to any file that's included in your tsconfig</span>
<span class="token keyword">import</span> type <span class="token punctuation">{</span> PaletteRange <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/joy/styles'</span><span class="token punctuation">;</span>

declare module <span class="token string">'@mui/joy/styles'</span> <span class="token punctuation">{</span>
  <span class="token keyword">interface</span> <span class="token class-name">ColorPalettePropOverrides</span> <span class="token punctuation">{</span>
    <span class="token comment">// apply to all Joy UI components that support `color` prop</span>
    secondary<span class="token operator">:</span> <span class="token boolean">true</span><span class="token punctuation">;</span>
  <span class="token punctuation">}</span>

  <span class="token keyword">interface</span> <span class="token class-name">Palette</span> <span class="token punctuation">{</span>
    <span class="token comment">// this will make the node `secondary` configurable in `extendTheme`</span>
    <span class="token comment">// and add `secondary` to the theme's palette.</span>
    secondary<span class="token operator">:</span> PaletteRange<span class="token punctuation">;</span>
  <span class="token punctuation">}</span>
<span class="token punctuation">}</span>