---
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. 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.

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

<CodeBlockLanguageDemo client:only="react" />

The 40 grammars it ships are `assembly`, `astro`, `bash`, `c`, `cpp`, `csharp`, `css`, `dart`, `dockerfile`, `elixir`, `git-diff`, `go`, `graphql`, `heex`, `html`, `ini`, `java`, `javascript`, `json`, `kotlin`, `lua`, `markdown`, `nginx`, `objective-c`, `perl`, `php`, `powershell`, `python`, `r`, `ruby`, `rust`, `scss`, `sql`, `svelte`, `swift`, `toml`, `tsx`, `typescript`, `vue` and `yaml`.

Common short forms are aliased: `js`, `jsx`, `ts`, `sh`, `shell`, `zsh`, `py`, `rb`, `md`, `yml`, `gql`, `docker`, `sass`.

A name outside that list fails its grammar load silently and renders unhighlighted, so check spelling against the list above if a block comes out plain.

### Browser Support

The CSS Custom Highlight API reached Baseline in June 2025, when Firefox 140 joined Chrome and Safari. Older browsers register no highlights and the code renders as unstyled monospace text — the block, its header, copy button and layout are unaffected, so the fallback costs colour only.

### Styling Limits

`::highlight()` accepts only `color`, `background-color`, `text-decoration`, `text-shadow` and `-webkit-text-stroke`/`-fill`. Bold and italic tokens are therefore unavailable: Markdown `**bold**` and `_italic_` runs and CSS `!important` take a colour rather than a weight or slant.

### 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 } from "react";

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

useEffect(() => {
  void scheduleHighlight();
}, [source]);

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

Two constraints come with it. The `<code>` element must contain a single text node — ranges are registered against that node, so a block whose `<code>` holds nested markup is skipped. And `scheduleHighlight` rescans the whole document rather than one block, because each pass replaces the ranges the previous one registered; calls made in the same frame are coalesced into a single pass, and passes never overlap. Blocks inside a shadow root are out of reach.

## 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`   | ❌       |