# ColorFunctions

# Color functions

The `@mantine/core` package exports several functions that can be used to manipulate colors
or extract information before using them as CSS values.

## darken and lighten

The `darken` and `lighten` functions can be used to manipulate color brightness.
They accept a color in any format as the first argument and the amount of lightness to add/remove as the second argument.

```tsx
import { darken, lighten } from '@mantine/core';

lighten('#228BE6', 0.1); // lighten by 10%
// -> rgba(56, 151, 233, 1)

darken('rgb(245, 159, 0)', 0.5); // darken by 50%
// -> rgba(123, 80, 0, 1)

darken('rgba(245, 159, 0, .3)', 0.5); // darken by 50%
// -> rgba(123, 80, 0, 1, .3)

lighten('var(--mantine-color-gray-4)', 0.74);
// -> color-mix(in srgb, var(--mantine-color-gray-4), white 74%)
```

## alpha

The `alpha` function converts a color to rgba format with a given alpha channel.
It is usually used to make colors more transparent. If it is not possible to convert the color to rgba
format (for example, if the color is a CSS variable), the function will use [color-mix](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color-mix).
Note that `color-mix` is not supported in some older browsers. You can check [caniuse](https://caniuse.com/mdn-css_types_color_color-mix)
for more information.

```tsx
import { alpha } from '@mantine/core';

alpha('#4578FC', 0.45); // -> rgba(69, 120, 252, 0.45)
alpha('var(--mantine-color-gray-4)', 0.74);
// -> color-mix(in srgb, var(--mantine-color-gray-4), transparent 26%)
```

## parseThemeColor

The `parseThemeColor` function returns information about a given color in the following format:

```tsx
interface ParseThemeColorResult {
  /**
   * True if the given color is a theme color. For example,
   * `blue`, `orange.9`, `pink.3` are theme colors,
   * while `#fff`, `rgba(0, 0, 0, .5)` are not
   */
  isThemeColor: boolean;

  /**
   * Key of `theme.colors` if the given color is a theme color. For example,
   * if the given color is `blue` it will be `blue`,
   * if the given color is `orange.9` it will be `orange`
   */
  color: string;

  /**
   * Resolved color value. For example,
   * if the given color is `blue.7` it will be the value of `theme.colors.blue[7]`,
   * if the given color is `#fff` it will be `#fff`
   */
  value: string;

  /**
   * If the given color is a theme color, this will be the shade of that color.
   * For example, if the given color is `blue.7` it will be `7`.
   * If the given color does not have an index or is not a theme color, then it will be `undefined`
   */
  shade: MantineColorShade | undefined;

  /**
   * Color CSS variable. For example:
   * `blue.7` – `--mantine-color-blue-7`,
   * `red` – `--mantine-color-red-filled`,
   * `white` – `--mantine-color-white`,
   * `#fff` – `undefined`
   */
  variable: CssVariable | undefined;
}
```

The `parseThemeColor` function can be used anywhere the `theme` object is available,
for example in [CSS variables resolver](https://mantine.dev/llms/styles-css-variables.md), [variant color resolver](https://mantine.dev/llms/theming-colors.md#colors-variant-resolver),
or component body:

```tsx
import {
  MantineColor,
  parseThemeColor,
  useMantineTheme,
} from '@mantine/core';

interface DemoProps {
  color: MantineColor;
}

function Demo({ color }: DemoProps) {
  const theme = useMantineTheme();
  const parsedColor = parseThemeColor({ color, theme });

  return (
    <div
      style={{
        backgroundColor: parsedColor.isThemeColor
          ? `var(${parsedColor.variable})`
          : parsedColor.value,
      }}
    />
  );
}
```

## getThemeColor

`getThemeColor` is a simpler version of the `parseThemeColor` function. It accepts a color string
as the first argument and a theme object as the second argument. It returns the parsed color value or CSS variable:

```tsx
import { getThemeColor, useMantineTheme } from '@mantine/core';

function Demo() {
  const theme = useMantineTheme();

  getThemeColor('blue', theme); // -> var(--mantine-color-blue-filled)
  getThemeColor('blue.7', theme); // -> var(--mantine-color-blue-7)
  getThemeColor('white', theme); // -> var(--mantine-color-white)
  getThemeColor('#DF78E4', theme); // -> #DF78E4
}
```

## getGradient

The `getGradient` function transforms a given `MantineGradient` object to a CSS gradient string:

```tsx
import { getGradient, useMantineTheme } from '@mantine/core';

function Demo() {
  const theme = useMantineTheme();

  getGradient({ deg: 180, from: 'blue', to: 'cyan.7' }, theme);
  // -> `linear-gradient(180deg, var(--mantine-color-blue-filled) 0%, var(--mantine-color-cyan-7) 100%)`
}
```

## isLightColor

The `isLightColor` function can be used to achieve better contrast between text and background:

```tsx
import { Box, isLightColor } from '@mantine/core';

interface DemoProps {
  color: string;
}

export function Demo({ color }: DemoProps) {
  return (
    <Box bg={color} c={isLightColor(color) ? 'black' : 'white'}>
      Box with contrast text
    </Box>
  );
}
```

## luminance

The `luminance` function returns the color luminance. It can be used to check color contrast:

```tsx
import { luminance } from '@mantine/core';

luminance('#fff'); // -> 1
luminance('#000'); // -> 0
luminance('#4578FC'); // -> 0.21726425554966
```