- Home
- Design system
- Elements
- 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.
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.
Apply the classes to <pre> to color an individual pane:
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.
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.
Height
The code pane defaults to 160px high and can be resized vertically. Content that exceeds its height or width scrolls.
Indent
Use --indent-* to change the top and left code padding, or --no-indent to remove it. The default is var(--space-small).
For individual edges, set padding on <pre>; axis-specific indent modifiers have no effect.
Gap
--gap-* changes the space between the caption and code pane. The default is var(--space-xsmall); --no-gap removes it.
--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 |
Styles
Variants
Light style
--light uses a light background and dark text.
Wrap style
--wrap wraps long lines and tokens while keeping a fixed-height pane.
Auto style
--auto grows the pane to fit its content and wraps long lines and tokens.
Composition
Used inside other components
Place the codeblock directly after the summary inside ds-disclosure for an edge-to-edge code pane.
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.
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 < and & as & inside <code> to display HTML source.
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