monday-ui-react-core/src/components/ThemeProvider/__stories__/ThemeProvider.mdx

Official monday.com UI resources for application development in React.js

import { Canvas, Meta } from "@storybook/blocks";
import {
  DescriptionWithLinkMondaySdkIntegration,
  ThemeProviderNegativeExampleTemplate,
  ThemeProviderPositiveExampleTemplate,
  TipDev,
  UsageGuidelinesThemeProvider
} from "./ThemeProvider.stories.helpers";
import * as ThemeProviderStories from "./ThemeProvider.stories";
import { Frame } from "vibe-storybook-components";

<Meta of={ThemeProviderStories} />

# ThemeProvider

<AlphaWarning />

- [Overview](#overview)
- [Props](#props)
- [Usage](#usage)
- [Variants](#variants)
- [Use cases and examples](#use-cases-and-examples)
- [Do’s and don’ts](#dos-and-donts)
- [Feedback](#feedback)

## Overview

This component helps to customize the colors of library's components by overriding a specific css variables with a values provided within <code>themeConfig</code> object.
There are 2 levels of theming: **system theme** and **product theme**.
System theme is a one of a 3 predefined themes: <code>light</code>(<code>.light-app-theme</code>), <code>dark</code>(<code>.dark-app-theme</code>) and <code>black</code>(<code>.black-app-theme</code>).
Product theme is a custom theme that can be provided by a user, there you can specify the values of specific color tokens for each of the system themes.

<Canvas of={ThemeProviderStories.Overview} />

## Props

<PropsTable />

## Usage

<UsageGuidelinesThemeProvider />

<TipDev />

## Variants

There are 3 system themes <code>light</code>, <code>dark</code> and <code>black</code>, and in each you can redefine the values of the following color tokens:

### Colors eligible for theming

<Frame>
  <Canvas of={ThemeProviderStories.ColorsEligibleForTheming} />
</Frame>

## Use cases and examples

### Theming scope

Only components wrapped with ThemeProvider will be affected by the <code>themeConfig</code>.

<Canvas of={ThemeProviderStories.ThemingScope} />

### Folded theming

If component is wrapped with multiple ThemeProviders, the most nested one will override the values of the outer one, but if the nested ThemeProvider doesn't provide a value for a specific color token, the outer ThemeProvider will be used.

<Canvas of={ThemeProviderStories.FoldedTheming} />

### Product theming

These are theme-definitions, which are used in monday.com products.

<Canvas of={ThemeProviderStories.ProductTheming} />

### Custom class selector

If you need to apply some of the tokens overrides only on elements under specific class you can declare theme like that:

<Canvas of={ThemeProviderStories.CustomClassSelector} />

### With systemTheme

In case there is not <b>system theme</b> defined on <code>body</code> tag (or on any other element upper in DOM hierarchy),
you can pass it as a prop to <code>ThemeProvider</code>.
It will set the <code>systemTheme</code> on <code>body</code> tag and will apply the corresponding theme.

<Canvas of={ThemeProviderStories.WithSystemTheme} />

### Integration with monday.com SDK in external applications

<DescriptionWithLinkMondaySdkIntegration />

<Canvas of={ThemeProviderStories.MondaySdkIntegration} />

## Do’s and Don’ts

<ComponentRules
  rules={[
    {
      positive: {
        component: [<ThemeProviderPositiveExampleTemplate />],
        description: "Pay attention and override all semantically close tokens, if needed."
      },
      negative: {
        component: [<ThemeProviderNegativeExampleTemplate />],
        description: "Don’t override only specific tokens to avoid inconsistent appearance"
      }
    }
  ]}
/>