---
title: Contrast Matrix
description: Compare foreground and background color pairs with contrast ratios and grades.
sidebar:
  order: 17
---

import previewCode from "../../snippets/contrast-matrix.mdx?raw";
import allCode from "../../snippets/contrast-matrix-all.mdx?raw";
import variantCode from "../../snippets/contrast-matrix-strict.mdx?raw";

<ComponentPreview path="contrast-matrix" code={previewCode} />

## Usage

Compare all named swatches from
[Colors](/colors). The opening preview limits the matrix to the first three
swatches to keep it compact.

```mdx
<ContrastMatrix />
```

## Examples

### Compare every named swatch

Omit `only` to include the complete configured swatch set on both axes. The
opening preview instead selects the first three IDs; use that approach to focus
on a subset without changing configuration order.

<ComponentPreview path="contrast-matrix-all" code={allCode} />

### Raise the pass threshold

Use `threshold` to decide which ratios receive a failing strike-through. This
example keeps the same three swatches as the opening preview and raises the
threshold to `7`.

<ComponentPreview path="contrast-matrix-strict" code={variantCode} />

## Reading and selecting pairs

Rows represent text colors and columns represent backgrounds. Cells show a
ratio rounded to two decimal places and a grade; the underlying unrounded ratio
is compared with `threshold`. Changing the threshold changes the strike-through,
not the grade calculation. Same-color cells show a dash instead of sample text.

`only` uses named swatch IDs from `brand.colors.swatches`. Filtering preserves
configuration order and silently omits unknown IDs. Unlike [Color Palette](/components/color-palette),
reordering IDs in `only` does not reorder the matrix.

## API reference

| Prop | Type | Default | Description |
| - | - | - | - |
| `brand?` | `BrandConfig` | `props.brand` | Override the resolved brand for this component. Supplied automatically in Brandtree MDX. |
| `ui?` | `UIStrings` | `props.ui` | Override interface strings for this component. Supplied automatically in Brandtree MDX. |
| `only?` | `string[]` | - | Restrict the matrix to named swatch IDs; configuration order is preserved. |
| `threshold?` | `number` | `4.5` | Ratio for normal body text. WCAG AA is 4.5. |
| `class?` | `string` | - | Additional class on the outer element. |