# color2k: Contrast

## getContrast(color1, color2)

```ts
function getContrast(color1: string, color2: string): number
```

Returns the contrast ratio between two colors based on the WCAG contrast
ratio formula.

The ratio is between 1 and 21 for opaque, in-range colors. Alpha is ignored,
and out-of-range channels such as `rgb(999, 0, 0)` are not clamped, so they
give ratios that mean nothing.

```js
getContrast('#444', '#fff'); // 9.739769120526205
```

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `color1` | `string` | The first color. |
| `color2` | `string` | The second color. |

### Returns

`number` - The contrast ratio between the two colors.

[Source](https://github.com/ricokahler/color2k/blob/main/src/getContrast.ts)

## getLuminance(color)

```ts
function getLuminance(color: string): number
```

Returns the relative luminance of a color using the WCAG formula.

```js
getLuminance('papayawhip'); // 0.877971001998354
```

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `color` | `string` | The input color. |

### Returns

`number` - A number between 0 for darkest black and 1 for lightest white.

[Source](https://github.com/ricokahler/color2k/blob/main/src/getLuminance.ts)

## hasBadContrast(color, standard, background)

```ts
function hasBadContrast(color: string, standard: 'decorative' | 'readable' | 'aa' | 'aaa' = 'aa', background: string = '#fff'): boolean
```

Returns whether a color fails a contrast threshold against a background.

The standards and the minimum contrast ratio each one needs are `decorative`
(1.5), `readable` (3), `aa` (4.5), and `aaa` (7). By default the color is
checked against `aa` on a white (`#fff`) background.

```js
hasBadContrast('red', 'aa'); // true
```

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `color` | `string` | The foreground color. |
| `standard` | `'decorative' \| 'readable' \| 'aa' \| 'aaa' = 'aa'` | The contrast standard to test against. Defaults to `aa`. |
| `background` | `string = '#fff'` | The background color. Defaults to `#fff`. |

### Returns

`boolean` - `true` when the contrast ratio is below the selected standard.

[Source](https://github.com/ricokahler/color2k/blob/main/src/hasBadContrast.ts)

## readableColor(color)

```ts
function readableColor(color: string): string
```

Returns black or white, whichever has better contrast against the given
color.

```js
readableColor('white'); // '#000'
```

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `color` | `string` | The background color. |

### Returns

`string` - `#000` or `#fff`.

[Source](https://github.com/ricokahler/color2k/blob/main/src/readableColor.ts)

## readableColorIsBlack(color)

```ts
function readableColorIsBlack(color: string): boolean
```

Returns whether black is the more readable color to place on top of the
input color.

This is the boolean form of `readableColor`.

```js
readableColorIsBlack('white'); // true
```

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `color` | `string` | The background color. |

### Returns

`boolean` - `true` when black is the more readable foreground color.

[Source](https://github.com/ricokahler/color2k/blob/main/src/readableColorIsBlack.ts)
