> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nemu.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Color

> Build a color from one input form and convert it to any other, then pass it anywhere a color is accepted

`Color` builds a color from one input form and converts it to any other. Construct it as a
call or with `new`; both work. You cannot mix input forms in a single call.

```ts theme={null}
import { Color } from "@nemu-ai/pdf";

const a = Color({ hex: "#2563eb" });
const b = new Color({ rgb: [37, 99, 235] });
const c = Color({ hsl: [217, 91, 60] });
```

## Input forms

A `Color` takes exactly one of the following keys. The shape of the accepted argument is the
`ColorInput` type.

```ts theme={null}
type ColorInput =
  | { hex: string }
  | { rgb: [number, number, number] }
  | { rgba: [number, number, number, number] }
  | { hsl: [number, number, number] }
  | { hsla: [number, number, number, number] };
```

<ParamField path="hex" type="{ hex: string }">
  A hex string such as `"#2563eb"`.
</ParamField>

<ParamField path="rgb" type="{ rgb: [number, number, number] }">
  Red, green, and blue channels from 0 to 255.
</ParamField>

<ParamField path="rgba" type="{ rgba: [number, number, number, number] }">
  Red, green, and blue channels from 0 to 255, plus an alpha from 0 to 1.
</ParamField>

<ParamField path="hsl" type="{ hsl: [number, number, number] }">
  Hue, saturation, and lightness.
</ParamField>

<ParamField path="hsla" type="{ hsla: [number, number, number, number] }">
  Hue, saturation, and lightness, plus an alpha from 0 to 1.
</ParamField>

<Note>
  Pass a single input form per `Color`. Mixing forms, for example `{ hex, rgb }`, is not supported.
</Note>

## Conversions and operations

A `Color` converts to any output form and supports common color operations. The operations
that return a color produce a new `Color` and leave the original unchanged.

```ts theme={null}
const a = Color({ hex: "#2563eb" });
const b = new Color({ rgb: [37, 99, 235] });

a.to_hex();      // "#2563eb"
a.to_hexa();
a.to_rgb();      // "rgb(37, 99, 235)"
a.to_rgba();     // "rgba(37, 99, 235, 1)"
a.to_hsl();
a.to_hsla();
a.alpha(0.5);    // a new Color at 50% opacity
a.lighten(0.1);
a.darken(0.1);
a.mix(b, 0.5);
a.luminance();
a.is_dark();     // true
```

<ParamField path="to_hex()" type="string">
  Returns the color as a hex string.
</ParamField>

<ParamField path="to_hexa()" type="string">
  Returns the color as a hex string including the alpha channel.
</ParamField>

<ParamField path="to_rgb()" type="string">
  Returns an `"rgb(...)"` string.
</ParamField>

<ParamField path="to_rgba()" type="string">
  Returns an `"rgba(...)"` string.
</ParamField>

<ParamField path="to_hsl()" type="string">
  Returns an `"hsl(...)"` string.
</ParamField>

<ParamField path="to_hsla()" type="string">
  Returns an `"hsla(...)"` string.
</ParamField>

<ParamField path="alpha(value)" type="Color">
  Returns a new `Color` with the given alpha, from 0 to 1.
</ParamField>

<ParamField path="lighten(amount)" type="Color">
  Returns a new `Color` lightened by `amount`.
</ParamField>

<ParamField path="darken(amount)" type="Color">
  Returns a new `Color` darkened by `amount`.
</ParamField>

<ParamField path="mix(other, ratio)" type="Color">
  Returns a new `Color` blended with `other` by `ratio`.
</ParamField>

<ParamField path="luminance()" type="number">
  Returns the relative luminance of the color.
</ParamField>

<ParamField path="is_dark()" type="boolean">
  Returns whether the color reads as dark.
</ParamField>

## Using a Color anywhere a color is accepted

A `Color` is accepted anywhere a color is, so `ColorLike = string | Color`. Any `color`,
`background_color`, or shape color field takes a hex string or a `Color`.

```ts theme={null}
import { Doc, Color } from "@nemu-ai/pdf";

const accent = Color({ hex: "#2563eb" });

const doc = new Doc({ page_size: "A4", margin: 54 });

doc.set_style({
  heading: { color: accent },
  link: { color: accent.lighten(0.1) },
  code: { background_color: accent.alpha(0.08) },
});
```

<Tip>
  Because operations return a new `Color`, you can derive a whole palette from one base color
  with `lighten`, `darken`, `alpha`, and `mix`.
</Tip>

See the [Reference](/packages/pdf/reference) for the full list of color related type exports,
including `ColorLike`, `ColorInput`, and `ColorValue`.