---
title: 'Color modes'
github: 'https://github.com/blockstack/ux/tree/master/packages/ui/src/color-modes'
---

# Color modes

This component is used to enable applications to style our components in different modes: light and dark.

> Note: many of our components have yet to be converted to use these color names.

## ColorModeProvider

To use, import the `ColorModeProvider` into the root of your application (such as `_app.tsx` for next.js applications,
or an App component for other react applications.) This component provides the context for our color mode to be
consumed within the application.

```tsx live=false
import { ColorModeProvider } from '@blockstack/ui';

// _app.tsx
const AppWrapper = ({ children, colorMode = 'light' }: AppWrapperProps => (
  <ThemeProvider>
    <CSSReset />
    <ColorModeProvider onChange={handleColorModeChange} colorMode={colorMode}>
        {children}
    </ColorModeProvider>
  </ThemeProvider>
);
```

### Provider Props

ColorModeProvider takes only a few props:

- `colorMode?: 'light' | 'dark'`
- `onChange?: (mode: string) => void`

### colorMode

Useful for setting a default value, or a passing a persisted set value to default to.

### onChange

This method is called when the the color mode is toggled via the `toggleColorMode` function that you can access via the
`useColorMode` hook. Here is an example to illustrate how one might persist the value to a cookie so that it can be
used in a server side rendered environment.

```tsx live=false
import { ColorModeProvider } from '@blockstack/ui';

import engine from 'store/src/store-engine';
import cookieStorage from 'store/storages/cookieStorage';

// _app.tsx

const COLOR_MODE_COOKIE = 'color_mode';
const cookieSetter = engine.createStore([cookieStorage]);
const handleColorModeChange = (mode: string) => cookieSetter.set(COLOR_MODE_COOKIE, mode);

const AppWrapper = ({ children, colorMode = 'light' }: AppWrapperProps => (
  <ThemeProvider>
    <CSSReset />
    <ColorModeProvider onChange={handleColorModeChange} colorMode={colorMode}>
        {children}
    </ColorModeProvider>
  </ThemeProvider>
);
```

## useColorMode

There is a color mode hook exposed that can be used to access the current `colorMode` value and a method to toggle the color mode.

```tsx live=false
import { useColorMode } from '@blockstack/ui';

export const ColorModeButton = forwardRef((props: LinkProps, ref: Ref<HTMLDivElement>) => {
  const { colorMode, toggleColorMode } = useColorMode();
  return (
    <IconButton onClick={toggleColorMode} title="Toggle color mode" {...props} ref={ref}>
      {colorMode === 'dark' ? <DarkModeIcon /> : <LightModeIcon />}
    </IconButton>
  );
});
);
```

## Colors

With the color modes component, we have a new way of naming our colors. Rather than them reflecting the name of each color, we now are using more semantically meaningful names. With this, we have exposed a helper function called `color` that allows you to pass in a name for one of the colors. This is useful because with typescript, it allows for autocomplete functionality and the ability to ensure strict typechecking on something like a color name.

```tsx live=false
import { color } from '@blockstack/ui';

// some-component.tsx
<Box background={color('bg-alt')} />;
```

Here are all of the type literals:

```tsx live=false
export type ColorsStringLiteral =
  | 'accent'
  | 'bg'
  | 'bg-alt'
  | 'bg-light'
  | 'invert'
  | 'text-hover'
  | 'text-title'
  | 'text-caption'
  | 'text-body'
  | 'input-placeholder'
  | 'border'
  | 'feedback-alert'
  | 'feedback-error'
  | 'feedback-success';
```
