Material Next
Home Install Components Marketing hub API Roadmap Changelog

Components

Code block

Readable, copyable code samples with Google Sans Code and lightweight syntax colours.

Stable<mnw-code-block>

import 'material-next-web-components/code-block.js';
On this page

Overview

Use <mnw-code-block> for install commands, configuration and short examples in documentation, release notes or a product's developer page. It shows the language as a label, colours common tokens and, with copy, adds a Copy action that writes the code to the clipboard.

Use something else when the reader must edit code (an editor such as CodeMirror), when exact highlighting matters for a language the built-in tokenizer does not know, or for very long files: the block has no line numbers, folding or search.

Live demo

Copy a snippet: its event shows here.

Copy works on HTTPS and localhost; the events report each copy.
<mnw-code-block language="bash" copy code="npm install material-next-web-components lit @material/web"></mnw-code-block>
<mnw-code-block language="html" copy>
  <template>
    <md-filled-button href="./install/">Get started</md-filled-button>
  </template>
</mnw-code-block>
<mnw-code-block language="text" code="No copy action: the copy attribute is off."></mnw-code-block>
<p class="demo-log" aria-live="polite">Copy a snippet: its event shows here.</p>
import 'material-next-web-components/code-block.js';

export default (root: HTMLElement) => {
  const log = root.querySelector('.demo-log')!;
  root.addEventListener('mnw-code-copy', (event) => {
    const {code} = (event as CustomEvent<{code: string}>).detail;
    log.textContent = `mnw-code-copy: ${code.length} characters on the clipboard`;
  });
  root.addEventListener('mnw-code-copy-error', () => {
    log.textContent = 'mnw-code-copy-error: the browser refused the clipboard';
  });
};

Usage

There are two ways to give it code:

  • The code attribute or property, for one-liners and for code you build in JavaScript. Newlines are kept; in HTML write them as real line breaks or &#10;.
  • The default slot, for multi-line markup. Wrap it in a <template> so the browser keeps it as text instead of rendering it. The block reads the slot's text content, so leading indentation is kept as written.

When both are present, code wins.

<mnw-code-block language="ts" copy code="const ready = true;"></mnw-code-block>

<mnw-code-block language="html" copy>
  <template><md-filled-button>Install</md-filled-button></template>
</mnw-code-block>

language is the label shown in the header and picks the highlighter: html (or markup) colours tags and attributes; every other value, text included, uses one script-style tokenizer that colours comments, strings, JavaScript and TypeScript keywords, capitalised names and numbers.

API

A Material code block with Google Sans Code typography, lightweight syntax colours and an optional copy action.

<mnw-code-block> properties
PropertyAttributeTypeDefaultDescription
languagelanguagestring'text'The programming language label displayed in the block header.
codecodestring''The code snippet to render. Slotted content is used when omitted.
copycopybooleanfalseShows the Material copy-to-clipboard action.
<mnw-code-block> events
EventDescription
mnw-code-copy-error{code, error} when the Clipboard API is missing or refuses; the block shows "Copy failed".
mnw-code-copy{code} after the code is written to the clipboard.
<mnw-code-block> slots
SlotDescription
DefaultCode as text, used when code is empty. Wrap markup in a <template> so the browser does not render it.
<mnw-code-block> CSS custom properties
Custom propertyDescription
--md-sys-color-code-backgroundCode surface.
--md-sys-color-code-on-backgroundCode text.
--md-sys-color-code-commentComment tokens.
--md-sys-color-code-punctuationPunctuation tokens.
--md-sys-color-code-tagMarkup tag tokens.
--md-sys-color-code-stringString tokens.
--md-sys-color-code-keywordKeyword tokens.
--md-sys-color-code-functionFunction name tokens.
--md-sys-color-code-variableVariable and number tokens.

The copy attribute is a boolean: present means on. Setting the property to false removes the attribute.

Accessibility

  • The code is a <figure> whose caption is the language label, around a <pre>, so assistive technology reads it as preformatted text.
  • The Copy action is a Material Web assist chip, reachable with the keyboard. After a copy, "Copied" (or "Copy failed") is announced through a polite live region, and the chip shows "Copied" for 1.4 seconds.
  • Syntax colours never carry meaning on their own.

Styling

The block reads the page's Material colour roles (--md-sys-color-*) for its surfaces and the --md-sys-color-code-* properties above for tokens, with light and dark defaults. Load Google Sans Code for the code font; it falls back to the platform's monospace font.

Limitations

  • The highlighter is a small built-in tokenizer, not Prism or Shiki. It has no grammar per language, so Bash, CSS or JSON get the script-style colours, and CSS or scripts inside HTML are not coloured.
  • Copy needs the Clipboard API, which browsers only allow in secure contexts (HTTPS or localhost). Listen for mnw-code-copy-error to offer another way.
  • Long lines scroll horizontally inside the block; they do not wrap.
 mail