Code Highlighter

Code highlighters display syntax-highlighted code with a copy button. Use them for code samples, install commands, and configuration snippets.

<wa-code-highlighter language="html">
  &lt;wa-button variant="brand"&gt;
    &lt;wa-icon slot="start" name="rocket"&gt;&lt;/wa-icon&gt;
    Launch
  &lt;/wa-button&gt;
</wa-code-highlighter>

Examples

Language

Set the language attribute to a grammar name or alias from the supported languages below. Grammars come from microlighter. Leave the language attribute empty to display plain text.

<wa-code-highlighter language="rust">
  fn main() {
      let crabs = ["Ferris", "Sebastian", "Mr. Krabs"];

      for crab in crabs.iter() {
          println!("Hello, {crab}!");
      }
  }
</wa-code-highlighter>

Loading Grammars

Bundled grammars ship with the component and highlight before the code block first paints. The rest load on demand the first time a language is used. Like other library assets, they load from assets/grammars/<name>.js relative to the base path. Each grammar is a plain ES module, so self-hosting the library's assets folder self-hosts the grammars too.

The element reports each stage of highlighting with a custom state and an event.

When no grammar matches, the code renders as plain text. To add a language, see Custom Grammars.

Escaping Code

Slotted code is parsed as HTML, so escape < as < and & as & where they'd be read as markup, such as in tags, generics, and character references. Comparisons and operators like x < 10 and a && b work as written.

<wa-code-highlighter language="ts">
  function firstOrDefault&lt;T>(items: T[], fallback: T): T {
    return items.length > 0 && items[0] !== undefined ? items[0] : fallback;
  }
</wa-code-highlighter>

To skip escaping, wrap the code in a <script type="text/plain"> element. Its content is read exactly as written. Code that contains </script> can't go in a script, so escape it or set the code property instead.

<wa-code-highlighter language="html">
  <script type="text/plain">
    <p class="menu">Fish &amp; chips</p>
  </script>
</wa-code-highlighter>

HTML formatters and minifiers leave <pre> alone, but they may collapse the whitespace inside custom elements. Exclude code highlighters from them, or set the code property instead.

Preserving Indentation

Common indentation and surrounding blank lines are removed by default, so slotted code can be indented to match the surrounding markup. Add the without-dedent attribute to keep slotted whitespace exactly as written, like a <pre> element. A single newline right after the opening tag is ignored.

<wa-code-highlighter language="yaml" without-dedent>
    # This block keeps its four-space indent
    name: Web Awesome
    version: 3</wa-code-highlighter>

Wrapping Long Lines

Long lines scroll horizontally by default. Add the wrap attribute to wrap them instead.

<wa-code-highlighter language="js" wrap>
  const message = 'This line is long enough to wrap onto the next line instead of making the code block scroll horizontally.';
</wa-code-highlighter>

Label

The code block is a region with the accessible name "Code". Use the label attribute to describe what the code is for.

<wa-code-highlighter language="bash" label="Install command">
  npm install @awesome.me/webawesome
</wa-code-highlighter>

Removing the Copy Button

A copy button appears when the pointer is over the code block or when it has focus. On touch devices, it's always visible. Add the without-copy attribute to remove it.

<wa-code-highlighter language="css" without-copy>
  .catfish {
    border-radius: 50%;
  }
</wa-code-highlighter>

Customizing

Token colors come from custom properties. Each one colors a group of related tokens, and its default is a pair of palette tokens for light and dark mode. Tokens can only change color, background color, and text decoration. The CSS Custom Highlight API doesn't support other properties, so tokens can't be bold or italic.

To recolor every code block on a page, set the custom properties on wa-code-highlighter in a stylesheet, like any other component custom property. To set them from :root or any ancestor instead, use the --syntax-* names described in Using microlighter Themes.

wa-code-highlighter {
  --keyword-color: light-dark(var(--wa-color-pink-40), var(--wa-color-pink-60));
  --string-color: light-dark(var(--wa-color-blue-40), var(--wa-color-blue-60));
}

To recolor a single block, set the custom properties on that element. Use light-dark() to pick a color for each mode.

<wa-code-highlighter language="js" class="code-highlighter-colors">
  // Count the fish in the sea
  const fish = ['catfish', 'swordfish', 'pufferfish'];
  console.log(`There are ${fish.length} kinds of fish`);
</wa-code-highlighter>

<style>
  .code-highlighter-colors {
    --comment-color: light-dark(var(--wa-color-pink-40), var(--wa-color-pink-60));
    --keyword-color: light-dark(var(--wa-color-orange-40), var(--wa-color-orange-60));
    --string-color: light-dark(var(--wa-color-cyan-40), var(--wa-color-cyan-60));
  }
</style>

The default and microlighter theme colors follow the color scheme. To show one code block in dark mode, add class="wa-dark" to it.

<wa-code-highlighter language="css" class="wa-dark">
  .moonwalk {
    animation: slide-back 2s ease-in-out infinite;
  }
</wa-code-highlighter>

Style the container with the pre part and the copy button with the copy-button__button part.

<wa-code-highlighter language="html" class="code-highlighter-container">
  &lt;wa-badge variant="success"&gt;Shipped&lt;/wa-badge&gt;
</wa-code-highlighter>

<style>
  .code-highlighter-container::part(pre) {
    background-color: var(--wa-color-surface-default);
    border: var(--wa-border-width-s) var(--wa-border-style) var(--wa-color-surface-border);
    border-radius: var(--wa-border-radius-l);
  }

  .code-highlighter-container::part(copy-button__button) {
    color: var(--wa-color-brand-on-quiet);
  }
</style>

Using microlighter Themes

The component reads the --syntax-* custom properties that microlighter themes set, so any theme stylesheet from the microlighter package works without changes. Load one and set the data-syntax-theme attribute on the <html> element. Every code highlighter on the page follows the theme.

<html data-syntax-theme="dracula">
  <head>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/microlighter@2/dist/themes/dracula.css" />
  </head>
  <body>
    <wa-code-highlighter language="js">
      const fish = ['catfish', 'swordfish', 'pufferfish'];
    </wa-code-highlighter>
  </body>
</html>

Each --syntax-* custom property becomes the default for the matching token custom property, such as --syntax-keyword for --keyword-color. The --syntax-background and --syntax-foreground custom properties color the pre part. Custom properties set on the element still win, so one block can override part of a theme.

To scope a theme, set the attribute on another element or on one code highlighter. This example sets it on the code highlighter and loads the stylesheet for the selected theme.

<div id="code-highlighter__microlighter">
  <wa-code-highlighter language="js">
    // Count the fish in the sea
    const fish = ['catfish', 'swordfish', 'pufferfish'];
    console.log(`There are ${fish.length} kinds of fish`);
  </wa-code-highlighter>

  <wa-divider></wa-divider>

  <wa-select label="Theme" value="dracula" style="width: 12rem">
    <wa-option value="none">None</wa-option>
    <wa-option value="cobalt2">Cobalt2</wa-option>
    <wa-option value="dracula">Dracula</wa-option>
    <wa-option value="github">GitHub</wa-option>
    <wa-option value="gruvbox">Gruvbox</wa-option>
    <wa-option value="min">Min</wa-option>
    <wa-option value="monokai">Monokai</wa-option>
    <wa-option value="night-owl">Night Owl</wa-option>
    <wa-option value="solarized-light">Solarized Light</wa-option>
    <wa-option value="tokyo-night">Tokyo Night</wa-option>
    <wa-option value="vesper">Vesper</wa-option>
    <wa-option value="vscode-plus">VS Code Plus</wa-option>
  </wa-select>
</div>

<script type="module">
  const container = document.getElementById('code-highlighter__microlighter');
  const highlighter = container.querySelector('wa-code-highlighter');
  const select = container.querySelector('wa-select');

  function applyTheme(name) {
    if (name === 'none') {
      highlighter.removeAttribute('data-syntax-theme');
      return;
    }

    if (!container.querySelector(`link[data-theme="${name}"]`)) {
      const link = document.createElement('link');
      link.rel = 'stylesheet';
      link.href = `https://cdn.jsdelivr.net/npm/[email protected]/dist/themes/${name}.css`;
      link.dataset.theme = name;
      container.append(link);
    }

    highlighter.setAttribute('data-syntax-theme', name);
  }

  await customElements.whenDefined('wa-select');
  applyTheme(select.value);
  select.addEventListener('change', () => applyTheme(select.value));
</script>

Themes follow Web Awesome's color scheme, not the operating system.

Providing Code Programmatically

Set the code property to display code from JavaScript. It takes precedence over slotted content and renders verbatim, without dedenting. Clear it to show the slotted code again.

<div id="code-highlighter__programmatic">
  <wa-code-highlighter language="css"></wa-code-highlighter>
  <wa-divider></wa-divider>
  <wa-textarea label="CSS" rows="4"></wa-textarea>
</div>

<script type="module">
  const container = document.getElementById('code-highlighter__programmatic');
  const highlighter = container.querySelector('wa-code-highlighter');
  const textarea = container.querySelector('wa-textarea');

  await customElements.whenDefined('wa-textarea');
  textarea.value = '.bookworm {\n  font-family: var(--wa-font-family-longform);\n}';
  highlighter.code = textarea.value;

  textarea.addEventListener('input', () => {
    highlighter.code = textarea.value;
  });
</script>

Custom Grammars

Register a TextMate grammar with the registerCodeGrammar() function to highlight another language or replace a built-in one. Language names can contain lowercase letters, numbers, hyphens, and underscores. Registered grammars apply immediately, even to code highlighters already on the page.

<wa-code-highlighter language="haiku">
  # An old silent pond
  frog jumps into the pond 1 time
  # Splash! Silence again
</wa-code-highlighter>

<script type="module">
  import { registerCodeGrammar } from '/dist/webawesome.js';

  registerCodeGrammar('haiku', {
    scopeName: 'source.haiku',
    patterns: [
      { match: '#.*$', name: 'comment.line.haiku' },
      { match: '\\b(jumps|into)\\b', name: 'keyword.control.haiku' },
      { match: '\\b\\d+\\b', name: 'constant.numeric.haiku' },
    ],
  });
</script>

Scope names pick the token colors. Most scopes map by their first segment, such as comment, keyword, or string, so the token custom properties apply to custom grammars too.

Accessibility Considerations

The code block is a region named "Code" in the user's language, or by the label attribute when set. It joins the tab order only when the code overflows, so keyboard users can reach and scroll it without an extra tab stop on short snippets. The copy button is labeled and announces when the code is copied.

When the code block has focus:

API

Importing

If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick a component manually, use one of the following snippets.

import 'https://ka-f.webawesome.com/[email protected]/components/code-highlighter/code-highlighter.js';

import '@awesome.me/webawesome/dist/components/code-highlighter/code-highlighter.js';

import './webawesome/dist/components/code-highlighter/code-highlighter.js';

import WaCodeHighlighter from '@awesome.me/webawesome/dist/react/code-highlighter/index.js';

Slots

Learn more about using slots.

Attributes & Properties

Learn more about attributes and properties.

Events

Learn more about events.

CSS Custom Properties

Learn more about CSS custom properties.

Custom States

Learn more about custom states.

CSS Parts

Learn more about CSS parts.

Dependencies

This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.

• <wa-copy-button>
• <wa-icon>
• <wa-popup>
• <wa-tooltip>

SSR

Learn more about Server-Side Rendering (SSR).

<wa-code-highlighter> renders an empty code block during SSR. The code and its highlighting appear after the component hydrates, because the Custom Highlight API needs a DOM.