Soracom

Design System
  1. Home
  2. Design system
  3. Elements
  4. Codeblock

Codeblock

Overview

ds-codeblock displays preformatted code or text, with an optional caption and pinned tag. Use it for API responses, configuration, commands, and logs.

Options

Basic usage

Place ds-codeblock on a <figure> containing <pre><code>. Use a <div> wrapper when figure semantics are not appropriate.

html
Copy

Component colors

Use the component color classes on the wrapper to set the code pane’s foreground. Add --background-* to set its background. These classes work independently, and local classes on <pre> take precedence over the wrapper.

html
Copy

Apply the classes to <pre> to color an individual pane:

html
Copy

For custom colors, set --color and --background-color on the wrapper or <pre>.

Caption

Add <figcaption> before the code pane to identify its content. Apply color and icon classes directly to the caption; wrapper colors affect only the code pane.

html
Copy

Pinned tag

Place a ds-tag --pinned before the code pane to label its language or file type. Leave space for the overlaid tag, as the blank first line does here.

html
Copy

Height

The code pane defaults to 160px high and can be resized vertically. Content that exceeds its height or width scrolls.

html
Copy

Indent

Use --indent-* to change the top and left code padding, or --no-indent to remove it. The default is var(--space-small).

html
Copy
Demo controls

For individual edges, set padding on <pre>; axis-specific indent modifiers have no effect.

html
Copy

Gap

--gap-* changes the space between the caption and code pane. The default is var(--space-xsmall); --no-gap removes it.

html
Copy
Demo controls

--v-gap-* and --h-gap-* do not independently change the caption spacing.

CSS custom properties

Property Default Effect
--ds-codeblock-height 160px Initial code-pane height; --auto sets it to auto on the pane
--ds-codeblock-min-height Twice the code inset plus var(--space-medium) Minimum code-pane height, including when resized
html
Copy

Styles

Variants

Light style

--light uses a light background and dark text.

html
Copy

Wrap style

--wrap wraps long lines and tokens while keeping a fixed-height pane.

html
Copy

Auto style

--auto grows the pane to fit its content and wraps long lines and tokens.

html
Copy

Composition

Used inside other components

Place the codeblock directly after the summary inside ds-disclosure for an edge-to-edge code pane.

html
Copy

Accessibility

Role and ARIA attributes

Name a scrollable pane with role="region" and aria-labelledby pointing to its caption, or use aria-label when there is no caption.

Keyboard access

Make a scrollable pane keyboard-accessible with tabindex="0". Keep a visible focus indicator so keyboard users can find the scrolling region.

html
Copy

The example restores the browser focus outline with outline: revert. You can style :focus-visible instead.

Text contrast

Check custom text/background pairs in light and dark themes. The results below use the normal-text threshold of 4.5:1 for AA.

Core styles

const active = true;

Default

const active = true;

--light

const active = true;

--auto

Examples

HTML source

Escape < as &lt; and & as &amp; inside <code> to display HTML source.

html
Copy

Manifest

The component manifest describes this component's API: its modifiers, structure, data attributes, CSS custom properties, accessibility notes, and example markup. It is consumed by tooling such as AI assistants and code generators.

Latest version: https://assets.soracom.io/sds/3.46.2/ds-codeblock/manifest.json?v=3.46.2

manifest.json
Copy