Code | NDS - Vanilla National Design System

Direct Code Block

Standalone code blocks with copy button, used for API documentation and code snippets

Basic Code Block


<div class="nds-card nds-stroke">
  <div class="nds-card-content">
    <span class="nds-card-title">Card Title</span>
    <p class="nds-card-description">Card description text</p>
  </div>
</div>


<div class="nds-code nds-expandable">
  <div class="nds-code-action">
    <button class="nds-btn nds-subtle nds-copy" aria-label="Copy code example">
      <i class="nds-icon nds-hgi-copy-01"></i>
    </button>
  </div>
  <div class="nds-expandable-content">
    <code class="lang-html code">
      <!-- Your code here -->
    </code>
  </div>
</div>

Code Block with Line Numbers


const alert = NDS.Alert.create({
    variant: 'success',
    title: 'Success',
    description: 'Your changes have been saved.',
    target: '#alert-container'
});

NDS.Alert.create({
    variant: 'info',
    title: 'Update Available',
    description: 'A new version is available.',
    target: '#container',
    closable: true,
    shadow: true
});


<div class="nds-code nds-expandable">
  <div class="nds-code-action">
    <button class="nds-btn nds-subtle nds-copy" aria-label="Copy code example">
      <i class="nds-icon nds-hgi-copy-01"></i>
    </button>
  </div>
  <div class="nds-expandable-content">
    <code class="lang-javascript">
      // Your code here
    </code>
  </div>
</div>

Expandable Code Block


async function handleFormSubmit(form) {
    const alertContainer = document.getElementById('form-alerts');

    // Clear previous alerts
    NDS.Alert.dismissAll(alertContainer);

    try {
        const response = await submitForm(form);

        if (response.success) {
            NDS.Alert.create({
                variant: 'success',
                description: 'Form submitted successfully!',
                target: alertContainer,
                title: 'Success',
                prepend: true
            });
        } else {
            NDS.Alert.create({
                variant: 'error',
                description: response.message,
                target: alertContainer,
                title: 'Submission Failed'
            });
        }
    } catch (error) {
        NDS.Alert.create({
            variant: 'error',
            description: 'An unexpected error occurred.',
            target: alertContainer,
            title: 'Error'
        });
    }
}


<div class="nds-code nds-expandable">
  <div class="nds-code-action">
    <button class="nds-btn nds-subtle nds-copy" aria-label="Copy code example">
      <i class="nds-icon nds-hgi-copy-01"></i>
    </button>
  </div>
  <div class="nds-expandable-content">
      <code class="lang-javascript">
    // Long code content here
    // Will collapse with "Show More" button
  </code>
  </div>
</div>

Tabbed Code Block

Code blocks with tab navigation for showing multiple languages or file types

Single Tab


<button class="nds-btn nds-primary nds-lg">
  <i class="nds-icon nds-hgi-plus-sign" aria-hidden="true"></i>
  <span class="nds-label">Button Text</span>
</button>


<div class="demo-code">
<div class="nds-tabs nds-code nds-divided">
  <div class="nds-tab-list-container nds-scroll-more">
    <nav class="nds-tab-list nds-scroll-more-content" role="tablist" aria-label="Tab navigation">
      <button class="nds-btn nds-subtle nds-tab" role="tab" aria-selected="true"
        aria-controls="panel-id" id="tab-id" type="button">
        <span class="nds-tab-label">HTML</span>
      </button>
    </nav>
    <button class="nds-btn nds-subtle nds-tab nds-show-more" aria-label="Show more" type="button"><i class="nds-icon nds-hgi-arrow-down-01" aria-hidden="true"></i>
    </button>
  </div>
  <div class="nds-tab-content">
    <div class="nds-tab-panel code-example" role="tabpanel" id="panel-id"
      aria-labelledby="tab-id">
      <div class="nds-code-action">
        <button class="nds-btn nds-subtle nds-copy" aria-label="Copy code example">
          <i class="nds-icon nds-hgi-copy-01"></i>
        </button>
      </div>
      <code class="lang-html code">
        <!-- Your code here -->
      </code>
    </div>
  </div>
</div>
</div>

Multiple Tabs


<div class="nds-alert nds-card" data-status="success">
  <span class="nds-feedback nds-alert-icon nds-outline">
    <span class="nds-feedback-icon">
      <i class="nds-icon" aria-hidden="true"></i>
    </span>
  </span>
  <div class="nds-alert-content">
    <div class="nds-alert-text">
      <span class="nds-alert-title">Success</span>
      <p class="nds-alert-description">Operation completed.</p>
    </div>
  </div>
</div>


NDS.Alert.create({
    variant: 'success',
    title: 'Success',
    description: 'Operation completed.',
    target: '#container'
});


.nds-alert {
  display: flex;
  align-items: flex-start;
  gap: var(--spacing-md);
  padding: var(--spacing-lg);
}


<div class="demo-code">
<div class="nds-tabs nds-code nds-divided">
  <div class="nds-tab-list-container nds-scroll-more">
    <nav class="nds-tab-list nds-scroll-more-content" role="tablist" aria-label="Tab navigation">
      <button class="nds-btn nds-subtle nds-tab" role="tab" aria-selected="true"
        aria-controls="panel-html" id="tab-html" type="button">
        <span class="nds-tab-label">HTML</span>
      </button>
      <button class="nds-btn nds-subtle nds-tab" role="tab" aria-selected="false"
        aria-controls="panel-js" id="tab-js" type="button">
        <span class="nds-tab-label">JavaScript</span>
      </button>
    </nav>
    <button class="nds-btn nds-subtle nds-tab nds-show-more" aria-label="Show more" type="button"><i class="nds-icon nds-hgi-arrow-down-01" aria-hidden="true"></i>
    </button>
  </div>
  <div class="nds-tab-content">
    <div class="nds-tab-panel code-example" role="tabpanel" id="panel-html"
      aria-labelledby="tab-html">
      <div class="nds-code-action">
        <button class="nds-btn nds-subtle nds-copy" aria-label="Copy code example">
          <i class="nds-icon nds-hgi-copy-01"></i>
        </button>
      </div>
      <code class="lang-html code">
        <!-- HTML code here -->
      </code>
    </div>
    <div class="nds-tab-panel code-example" role="tabpanel" id="panel-js"
      aria-labelledby="tab-js" hidden>
      <div class="nds-code-action">
        <button class="nds-btn nds-subtle nds-copy" aria-label="Copy code example">
          <i class="nds-icon nds-hgi-copy-01"></i>
        </button>
      </div>
      <code class="lang-javascript code">
        // JavaScript code here
      </code>
    </div>
  </div>
</div>
</div>

Hidden Code in Demo Cards

When used inside demo cards, tabbed code blocks start with the hidden attribute. The showcase JavaScript reveals them with a toggle button. Click the code icon below any demo card to see this in action.


<!-- Inside a .nds-demo-card, add hidden attribute -->
<div class="demo-code">
<div class="nds-tabs nds-code nds-divided">
  <!-- Tab structure same as above -->
</div>
</div>

Inline Code

Use nds-inline-code on a <code> element for short inline code references with syntax coloring

Inline Code

Call NDS.Code.init after inserting dynamic code blocks, or use the class nds-inline-code directly on any <code> element.


<p>Call <code class="nds-inline-code lang-html">NDS.Code.init</code> after inserting dynamic code blocks, or use the class <code class="nds-inline-code lang-html">nds-inline-code</code> directly on any <code class="nds-inline-code lang-html">&lt;code&gt;</code> element.</p>

Language Classes

Supported language identifiers for the code element. When no class is present, the lexer sniffs the language from the content automatically.

Available Language Classes

Class	Language	Usage
`lang-html`	HTML / XML	Markup and template examples
`lang-css`	CSS	Stylesheet examples. SCSS-only syntax (`$vars`, `@mixin`, `//` comments) is not lexed
`lang-javascript` or `lang-js`	JavaScript	Script and API examples
`lang-markdown` or `lang-md`	Markdown	Docs and agent-instruction blocks. Headings, list and quote markers, links, bold, and inline code are coloured. A fenced block is lexed as its info-string language (```html, ```css, ```js); any other info string renders the body as a flat code run. Prose-length lines soft-wrap instead of scrolling horizontally — the wrap is visual only, so copied text keeps the authored line breaks
`lang-prompt`	AI prompt	Prompt text written to be pasted into a coding agent. Colours the parts the reader must check before sending: paths and filenames, `SCREAMING_CASE` placeholders and markers, and quoted phrases. Wraps like Markdown

Built-in Features

Syntax Highlighting

HTML, CSS, JavaScript, Markdown, and agent prompts are highlighted automatically. Embedded <style> and <script> bodies inside HTML blocks are highlighted in their respective languages.

Line Numbers

Every block gets a CSS counter gutter — no class needed. The gutter is reserved in CSS so it paints before the highlighter loads, and the line digits drop into it without shifting your code. Markdown blocks skip the gutter — their lines soft-wrap, so one digit would sit beside several visual rows.

Language Label

Each block names its language with an nds-tag in the top corner opposite the action bar, stamped from the authored lang-* class — so it names languages the highlighter doesn't lex too (lang-bash, lang-json). Every block carries one: in a tabbed block the tag sits in each panel, and a block with no lang-* class is named from the sniffed language. To place extra badges beside it, author a .nds-code-tags strip (see Usage Guidelines).

Copy Button

Add nds-copy to any button inside .nds-code-action to copy the block's source text. The component sizes that button itself — nds-icon-only nds-md is stamped at init, so no block needs the classes in its markup; a button carrying a visible label keeps its width. The button shows a brief "Copied" state on success.

Language Auto-detection

When no lang-* class is set, the lexer sniffs the language from the content: leading < implies HTML, JS keywords imply JavaScript, selector or declaration patterns imply CSS. A lang-* class that names a language we don't lex renders as plain text — your label is never overridden by a guess.

Inline Code

Apply nds-inline-code to a <code> element for short inline references. Coloring comes straight from the lang-* class in CSS, so inline code is correct at first paint with no JavaScript.

Themeable Tokens

Six role-named --syntax-* custom properties let you override every syntax color at the page or component level. Each ships a light and a dark value that clears WCAG AA contrast.

Usage Guidelines

Authored Tag Strip

To place extra badges beside the language tag (a version tag, a status chip), author a .nds-code-tags strip as a direct child of the block. The strip replaces the auto-stamped label — the authored .nds-code-lang chip inside it suppresses the stamp — and it carries the block's lang-* class so it clears the line-number gutter the same way the stamped tag would. Extra chips are ordinary nds-tag elements.


<div class="nds-code">
  <span class="nds-code-tags lang-html">
    <span class="nds-tag nds-gray nds-xs nds-code-lang lang-html"><span class="nds-label">HTML</span></span>
    <span class="nds-tag nds-green nds-xs"><span class="nds-label">v3</span></span>
  </span>
  <div class="nds-code-action">…</div>
  <code class="lang-html">…</code>
</div>

Data Attributes

Attribute	Element	Description
`data-nds-code-processed`	`code`	Set to `true` by JS after highlighting. Guards against double-processing. Set to `false` by `reprocessCodeElement` before re-highlighting.

CSS Custom Properties

These properties apply to both .nds-code and .nds-inline-code. Set them on a parent element or :root to re-theme all code on the page. Each is named for the role it colors, and setting one overrides both light and dark mode.

Property	Light	Dark	Highlights
`--syntax-tag`	`--colors-red-600`	`--colors-red-400`	HTML tags and CSS selectors
`--syntax-attr`	`--colors-yellow-700`	`--colors-yellow-400`	Attribute names and numbers
`--syntax-string`	`--colors-green-700`	`--colors-green-400`	Attribute values, strings and template literals
`--syntax-property`	`--colors-blue-600`	`--colors-blue-400`	CSS property names
`--syntax-keyword`	`--colors-tertiary-500`	`--colors-tertiary-300`	Keywords, literals and built-in globals
`--syntax-comment`	`--colors-neutral-500`	`--colors-neutral-400`	Comments
`--code-max-height`	`60svh`		Height a block scrolls inside instead of growing the page

JavaScript API

The NDS.Code API is called automatically on page load. Call NDS.Code.init() after inserting code blocks dynamically.


// ── Initialize all code blocks on the page ───────────
// Processes every `.nds-code code`. Inline code needs no JS — it is
// coloured in CSS from its lang-* class.
NDS.Code.init();

// ── Re-highlight a single element ────────────────────
// Re-lexes in place from the element's text. Use after a dynamic
// content change. Safe to call repeatedly.
NDS.Code.reprocessCodeElement(codeEl);

// ── Detect the language of a block ───────────────────
// Returns 'html', 'css', 'javascript', 'markdown', 'prompt', or null
// when a lang-* class
// names a language we don't lex (the block then renders as plain text).
// Reads the lang-* / language-* class first; a block with no lang
// class at all falls back to content sniffing.
const lang = NDS.Code.detectLanguage(codeEl, sourceText);

Code Block - National Design System

Direct Code Block

Tabbed Code Block

Inline Code

Language Classes

Built-in Features

Usage Guidelines

Authored Tag Strip

Data Attributes

CSS Custom Properties

JavaScript API