---
title: "Code Block"
description: "Syntax-highlighted code display with status variants"
source: "Equality"
---
import { CodeBlock } from "@eqtylab/equality";

import {
  CodeBlockLanguageDemo,
  CodeBlockLineNumbersDemo,
  CodeBlockNeutralDemo,
} from "@demo/components/demo/code-block";

## Overview

The Code Block component comes with syntax highlighting and five color variants to visually communicate different statuses or contexts:

- **Neutral:** The default style, suitable for general blocks of code.
- **Primary:** Alternate style, general highlight.
- **Warning:** Highlights code that may have caveats, edge cases, or requires extra attention.
- **Danger:** Highlights code that can cause errors or undesirable outcomes.
- **Success:** Highlights recommended or preferred code patterns.

## Usage

Import the component:

```tsx
import { CodeBlock } from "@eqtylab/equality";
```

`code` is a required prop and should be set to the string of code you want to appear within the code block. Set the code language by using the `language` prop.

For example:

```tsx
const code = `
console.log('Hello, world!');
`;

<CodeBlock language="js" code={code} />;
```

`neutral` is the default variant. Select another by using the `variant` prop, for example:

```tsx
<CodeBlock title="Error" variant="danger" language="js" code={code} />
```

## Code Language Support

The Code Block component highlights with [MicroLighter](https://github.com/davatron5000/microlighter), which reads TextMate grammars and paints them through the [CSS Custom Highlight API](https://developer.mozilla.org/en-US/docs/Web/API/CSS_Custom_Highlight_API). Grammars load on demand, so a page only pays for the languages it actually renders.

The language **must** be passed via the `language` prop for syntax highlighting to work. Anything unrecognised — including the `text` default — renders as unstyled monospace text. For a full list of supported languages, see Microliter's readme.

```tsx
<CodeBlock language="json" code={code} />
```

<CodeBlockLanguageDemo client:only="react" />

### Highlighting Your Own Markup

If you render code outside this component — a diff view or an editor, say — `CODE_BLOCK_ATTRIBUTE` and `scheduleHighlight` opt that markup into the same pass, so it picks up the same palette:

```tsx
import { useEffect, useRef } from "react";

import { CODE_BLOCK_ATTRIBUTE, scheduleHighlight } from "@eqtylab/equality";

const ref = useRef<HTMLPreElement>(null);

useEffect(() => {
  void scheduleHighlight(ref.current?.getRootNode());
}, [source]);

<pre ref={ref} {...{ [CODE_BLOCK_ATTRIBUTE]: "" }}>
  <code className="language-rust">{source}</code>
</pre>;
```

The `<code>` element must only contain text — a block that wraps its lines in markup is skipped. Call `scheduleHighlight` again whenever the code changes or the block is removed; calls made in the same frame are coalesced, so calling it freely is fine.

Pass the block's root, `pre.getRootNode()`. If left out, the pass covers the document, which cannot see into a shadow root. A block inside a shadow root also needs the palette adopted into that root, since the component's stylesheet only reaches the document. Highlighting a shadow root clears the colours on the document's blocks and the reverse, so for now the two cannot both stay highlighted.

## Line Numbers

Set `lineNumbers` to number every line in a gutter beside the code. The gutter is sticky, so the numbers stay in place while long lines scroll under them.

Numbering and wrapping are mutually exclusive: a wrapped line occupies more rows than its number does, which would drift the two columns apart. Setting `lineNumbers` therefore switches long lines from wrapping to scrolling horizontally.

<CodeBlockLineNumbersDemo client:only="react" />

## Color Variants

Code blocks support color variants using either the brand primary color or status options. Available variants are `neutral`, `primary` (brand primary color), `success`, `danger`, and `warning`. Use these to visually distinguish different types of code or contexts according to your design needs.

### Neutral (default)

<CodeBlockNeutralDemo client:only="react" />

### Success

<CodeBlock
  title="Success"
  language="js"
  code="console.log('Hello, world!');"
  variant="success"
  client:only="react"
/>

### Danger

<CodeBlock
  title="Danger"
  language="js"
  code="console.log('Hello, world!');"
  variant="danger"
  client:only="react"
/>

### Warning

<CodeBlock
  title="Warning"
  language="js"
  code="console.log('Hello, world!');"
  variant="warning"
  client:only="react"
/>

## Title

The Code Block component supports arbitrary titles:

<CodeBlock
  title="Custom Title"
  language="js"
  code="console.log('Hello, world!');"
  client:only="react"
/>

## Code Label

The Code Block component supports arbitrary code labels:

<CodeBlock
  title="Example"
  language="js"
  codeLabel="/* This is a code label - it won't be copied to the clipboard */"
  code="console.log('Hello, world!');"
  client:only="react"
/>

## Props

| Name          | Description                                                                           | Type                                                 | Default   | Required |
| ------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------- | --------- | -------- |
| `code`        | String of text to display within the code block as code.                              | `string`                                             | —         | ✅       |
| `language`    | The language of the code for syntax highlighting.                                     | `string`                                             | `text`    | ❌       |
| `variant`     | The visual style variant of the code block.                                           | `neutral`, `primary`, `success`, `warning`, `danger` | `neutral` | ❌       |
| `title`       | Text to display as the title.                                                         | `string`                                             | —         | ❌       |
| `codeLabel`   | Text to display as the code label.                                                    | `string`                                             | —         | ❌       |
| `copy`        | String to copy when the copy button is clicked. Falls back to `code` if not provided. | `string`                                             | —         | ❌       |
| `lineNumbers` | Number every line in a gutter. Long lines scroll instead of wrapping while set.       | `boolean`                                            | `false`   | ❌       |