Skip to content
+

Color inversion

Joy UI components can invert their colors to match with the parent's variant.

Motivation

The Joy UI global variants feature provides a consistent set of values for the variant prop. But these variants can sometimes cause quirks when the same styles are applied to both parent and child components. Check out the two demo cards below to see how things can go wrong:

New

Learn how to build super fast websites.

One layer
Global variants are applied only to the children.

New

Learn how to build super fast websites.

Two layers
Global variants are applied to the card and children.

  • On the left, the Button variant is solid, while its parent Card is the default outlined, so the design works well.
  • On the right, the solid variant is applied to both the Button and the Card, disrupting the design's hierarchy and contrast.

Joy UI's color inversion feature prevents this kind of situation from occurring, while still preserving the hierarchical meaning of the global variants themselves.

Overview

When color inversion is enabled on a parent component, all children components invert their styles (regardless of their respective color props) to match the parent's background. The inverted styles maintain the semantic meaning of their corresponding global variants—in the example below, the Button is still solid even though it's been inverted to contrast with its container. If you change the Button's variant to outlined, you'll see that the design still works; but try removing the invertedColors prop from the parent Card, and you'll see how the design falls apart (and thus, why this feature is so useful):

New

Learn how to build super fast websites.

Benefits

  • Color inversion reduces a significant amount of styling effort. It handles all of the visual states (hover, active, and focus) on all the children.
  • It makes your interface scalable. New components added to the area will just work.
  • It works for both client-side and server-side rendering.
  • It works for both light and dark mode.
  • It can be disabled at any time without impacting the structure of the components.
  • It is an opt-in feature. If you don't use it, the extra CSS variables won't be included in the production style sheet.
  • Some children can be excluded from the color inversion, see "skip color inversion on a child" section.

Trade-offs

  • If the parent component contains just a few children, the size of the stylesheet generated may be significantly larger than it would be if you customized each child individually. (This may be inconsequential for overall performance.)
  • It doesn't work with browsers that don't support CSS variables.

Usage

Supported components

The following components accept the invertedColors prop when applied in conjunction with the solid or soft variants:

$4,236

CREDIT

•••• •••• •••• 1212

CARD NAME

JOHN DOE

EXPIRE

07/25

$4,236

CREDIT

•••• •••• •••• 1212

CARD NAME

JOHN DOE

EXPIRE

07/25

Press Enter to start editing

Exceptions

Color inversion does not affect the popup slot of the Autocomplete, Menu, or Tooltip components by default. To enable it, set disablePortal to "true" using slotProps on the respective child component, as demonstrated below:

Skip inversion on a child

When invertedColors is applied to a parent, you can add the data-skip-inverted-colors attribute to a child to prevent that child from being inverted.

Design Thinking

How to apply design thinking to your problem in order to generate innovative and user-centric solutions.

Apply color inversion to any parent

import { applySolidInversion, applySoftInversion } from '@mui/joy/colorInversion';

If you need color inversion for a parent component that isn't supported by default, you can use the applySolidInversion or applySoftInversion utilities to add it to any component that contains children. (This is what the supported components use behind the scenes when the invertedColors prop is applied.)

The examples below show how to use these utilities with both the sx prop and the styled API:

With the sx prop

<Box sx={[{ ...baseStyles }, applySolidInversion('neutral')]}>...</Box>

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

4M

Weekly downloads

87k

Stars on GitHub

2.7k

Open source contributors

18.4k

Followers on X

With the styled API

const Parent = styled('div')([{ ...baseStyles }, applySolidInversion('neutral')]);

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

4M

Weekly downloads

87k

Stars on GitHub

2.7k

Open source contributors

18.4k

Followers on X

How it works

Color inversion adds CSS variables to the component using the invertedColors prop or the apply utilities. There's no React context involved in this feature.

<Sheet invertedColors variant="solid" color="neutral">

// The parent's style sheet
{
  // the values of these variables depends on the parent's variant and color.
  --variant-softColor:;
  --variant-softBg:;
  --variant-softHoverColor:;
  --variant-softHoverBg:;
  --variant-softActiveBg:;// other variants
  --joy-palette-text-primary:;
  --joy-palette-text-secondary:;
  --joy-palette-text-tertiary:;
  --joy-palette-background-surface:;// other theme palette tokens
}

As a result, the children will use these CSS variables instead of the theme:

// The children style sheet
// The values of these variables are inherited from the parent.
{
  color: var(--joy-palette-text-primary);
  background: var(--joy-palette-background-surface);}

Common examples

⌘K
2


Intro to the MUI ecosystem

Blog post
  • Sitemap
    • Services
    • Blog
    • About
  • Products
    • Joy UI
    • Base UI
    • Material UI

Side navigation

    Dashboard
    Chat
    5
    Team
  • Shortcuts
      Tasks
      Reports
35%
Active

Last update: 22/12/22

7

Marketing section

Get started

Instant access to the power of the Joy UI library.