Warning

This is an internal project, and is not intended for public use. No support or stability guarantees are provided.

Code Highlighter

The CodeHighlighter component provides a powerful and flexible way to display interactive code examples with syntax highlighting, multiple variants, and live previews. It supports both static code blocks and interactive demos with component previews.

The component uses the Props Context Layering pattern to work seamlessly across server and client boundaries, allowing progressive enhancement from static code to interactive demos.

Features

Syntax highlighting with support for multiple languages using Starry Night
Live component previews alongside code
Multiple Variant support for showing different implementation styles
Automatic Transformations from TypeScript to JavaScript
Lazy loading with fallback content
Lazy syntax highlighting for performance optimization
Customizable content renderers
Hybrid rendering support for build, server, or client-time loading, parsing, and transforming
Webpack integration for build-time pre-computation

Basic Usage

Let's start with the fundamentals. CodeHighlighter can display simple code blocks with syntax highlighting, perfect for documentation where you just need to show code examples:

Simple Code Block

We can use it to highlight code snippets in various languages, like JavaScript, TypeScript, or even CSS.

console.log('Hello, world!');

import * as React from 'react';
import { Code } from './CodeBlock';

export function BasicCode() {
  return (
    <Code fileName="hello.js">{`console.log('Hello, world!');`}</Code>
  );
}

ExpandCollapse

But CodeHighlighter really shines when you want to combine working React components with their source code. This creates an interactive experience where users can see both the rendered output and the implementation.

Interactive Demo

Checkbox

import * as React from 'react';
import { Checkbox } from '@/components/Checkbox';

export function CheckboxBasic() {
  return (
    <Checkbox defaultChecked />
  );
}

import { CheckboxBasic } from './CheckboxBasic';
import { createDemo } from './createDemo';

export const DemoCheckboxBasic = createDemo(import.meta.url, CheckboxBasic);

ExpandCollapse

Demo Factory Pattern

Tip

New to the overall approach? See the broader Built Factories Pattern for why factories use import.meta.url, how variants are derived, and the server vs client split.

Note

Before you can use createDemo() in your demos, you must first create this factory function in your repo (see the abstractCreateDemo docs for details).

To unlock CodeHighlighter's full potential—especially build-time optimization—you'll need to use the factory pattern. This isn't just a convention; it's required for precomputation to work.

The factory pattern uses createDemo() to structure your demos in a way that the webpack loader can process and cache at build time. You implement createDemo within your app using abstractCreateDemo to define the structure and behavior of your demos.

Factory Structure

All demos must use this structure in an index.ts file:

// app/components/checkbox/demos/basic/index.ts
import { createDemo } from '../createDemo';
import { Checkbox } from './Checkbox';

export const DemoCheckboxBasic = createDemo(import.meta.url, Checkbox);

For multiple variants:

// app/components/checkbox/demos/basic/index.ts
import { createDemoWithVariants } from '../createDemo';
import { Checkbox as CssModules } from './css-modules/Checkbox';
import { Checkbox as Tailwind } from './tailwind/Checkbox';

export const DemoCheckboxBasic = createDemoWithVariants(import.meta.url, { CssModules, Tailwind });

Demo File Structure

When using the factory pattern with precomputation, organize your demo files like this:

app/components/checkbox/demos/
  basic/
    index.ts             # Factory file (processed by webpack loader)
    Checkbox.tsx         # Component implementation
    Checkbox.module.css  # Dependencies (auto-loaded)

This follows Next.js' file based routing conventions, similar to how app/components/checkbox/page.tsx is built as a "page", app/components/checkbox/demos/basic/index.ts is built as a "demo".

This also allows demo components to follow internal naming conventions, like CheckboxBasic.tsx that has a named export of CheckboxBasic, while the demo itself can be loaded by importing ./demos/basic (without needing to specify the index file).

It allows imports to remain the same when variants are added, e.g. import { DemoCheckboxBasic } from './demos/basic' will still work even if the demo is split into multiple variants.

app/components/checkbox/demos/
  basic/
    index.ts               # Factory file (processed by webpack loader)
    tailwind/
      index.ts             # Simple re-export of the implementation (optional)
      Checkbox.tsx         # Component implementation
    css-modules/
      index.ts             # Simple re-export of the implementation (optional)
      Checkbox.tsx         # Component implementation
      Checkbox.module.css  # Dependencies (auto-loaded)

Webpack Loader Integration

The precomputation is handled by a webpack loader that processes demo files at build time, enabling caching by the contents of the demo index file and all of its dependencies.

Note

For detailed information about the webpack loader implementation, configuration, and advanced usage, see the Precompute Loader Documentation.

Tip

Client-Side Implementation: For client-side loading, highlighting, and transforms, see the Code Provider Documentation which provides detailed examples of runtime processing.

Important: Precomputation only works:

✓ In files matching the webpack loader pattern (default: ./app/**/demos/*/index.ts)
✓ Using createDemo()
✓ In both main demos and nested demo examples
× Not in direct CodeHighlighter usage
× Not in files outside the configured loader pattern

Advanced Features

Once you've mastered the basics, CodeHighlighter offers several powerful features for more sophisticated use cases.

Demo Variants

Sometimes you want to show different approaches to the same problem: CSS Modules versus Tailwind, Hooks or Blocks pattern, or different implementation strategies. CodeHighlighter makes this seamless with variant switching. Your components can even appear differently, but we recommend keeping them as similar as possible to avoid confusion.

Checkbox

import * as React from 'react';
import { Checkbox } from '@/components/Checkbox';

import styles from './CheckboxRed.module.css';

export function CheckboxRed() {
  return (
    <Checkbox defaultChecked className={styles.root} />
  );
}

import { CheckboxRed as CssModules } from './css-modules/CheckboxRed';
import { CheckboxRed as Tailwind } from './tailwind/CheckboxRed';
import { createDemoWithVariants } from './createDemo';

export const DemoCheckboxRed = createDemoWithVariants(import.meta.url, { CssModules, Tailwind });

ExpandCollapse

Code Transformed

One of CodeHighlighter's most powerful features is automatic code transformation. Write your examples in TypeScript, and users can instantly see the JavaScript equivalent:

const x: number = 1;
interface Props { name: string; }

import * as React from 'react';
import { Code } from './Code';

export function BasicCode() {
  return (
    <Code fileName="example.ts">{`const x: number = 1;\ninterface Props { name: string; }`}</Code>
  );
}

ExpandCollapse

Code Highlight Idle

For pages with many code examples, you can defer syntax highlighting until the browser is idle, keeping your initial page loads fast:

console.log('Hello, world!');

import * as React from 'react';
import { Code } from './Code';

export function BasicCode() {
  return (
    <Code fileName="hello.js">{`console.log('Hello, world!');`}</Code>
  );
}

ExpandCollapse

Demo Fallback

Good user experience means showing meaningful feedback during loading. The fallback content is also what search engines and AI bots see in the initial HTML, making it crucial for SEO and content discovery. CodeHighlighter supports custom loading components and skeleton loaders:

Checkbox

import * as React from 'react';
import { Checkbox } from '@/components/Checkbox';
import styles from './CheckboxRed.module.css';

export function CheckboxRed() {
  return (
    <Checkbox className={styles.root} defaultChecked />
  );
}

import { CheckboxRed } from './CheckboxRed';
import { createDemo } from './createDemo';

export const DemoCheckboxRed = createDemo(import.meta.url, CheckboxRed);

Demo Fallback All Files

When fallbackUsesExtraFiles is enabled, the fallback content receives all extra files from the selected variant. This means search engines and AI bots will see all the component's related files (CSS, utilities, etc.) in the initial HTML, improving content discoverability. Note that the complete list of filenames is always available for navigation, regardless of this setting:

Checkbox

import * as React from 'react';
import { Checkbox } from '@/components/Checkbox';
import styles from './CheckboxRed.module.css';

export function CheckboxRed() {
  return (
    <Checkbox className={styles.root} defaultChecked />
  );
}

.root {
  background-color: #e5484d !important;
  border-color: #e5484d !important;
}

import { CheckboxRed } from './CheckboxRed';
import { createDemo } from './createDemo';

export const DemoCheckboxRed = createDemo(import.meta.url, CheckboxRed);

Demo Fallback All Variants

When fallbackUsesAllVariants is enabled, the fallback content receives data for all available variants. This ensures that search engines and AI bots can see all implementation approaches (CSS Modules, Tailwind, etc.) in the initial HTML, making your documentation more comprehensive for automated indexing. Note that the complete list of filenames is always available for navigation, regardless of this setting:

Checkbox

import * as React from 'react';
import { Checkbox } from '@/components/Checkbox';

import styles from './CheckboxRed.module.css';

export function CheckboxRed() {
  return (
    <Checkbox defaultChecked className={styles.root} />
  );
}

.root {
  background-color: #e5484d !important;
  border-color: #e5484d !important;
}

Tailwind

import { CheckboxRed as CssModules } from './css-modules/CheckboxRed';
import { CheckboxRed as Tailwind } from './tailwind/CheckboxRed';
import { createDemoWithVariants } from './createDemo';

export const DemoCheckboxRed = createDemoWithVariants(import.meta.url, { CssModules, Tailwind });

import * as React from 'react';
import { Checkbox } from '@/components/Checkbox';

import styles from './CheckboxRed.module.css';

export function CheckboxRed() {
  return (
    <Checkbox defaultChecked className={styles.root} />
  );
}

import * as React from 'react';
import { Checkbox } from '@/components/Checkbox';

export function CheckboxRed() {
  return (
    <Checkbox defaultChecked className="bg-red-500" />
  );
}

import 'server-only';

import {
  createDemoFactory,
  createDemoWithVariantsFactory,
} from '@mui/internal-docs-infra/abstractCreateDemo';

import { DemoContentLoading } from './DemoContentLoading';
import { DemoContent } from './DemoContent';

const projectDir = process.env.SOURCE_CODE_ROOT_DIR;
const projectUrl = process.env.SOURCE_CODE_ROOT_URL;

/**
 * Creates a demo component for displaying code examples with syntax highlighting.
 * @param url Depends on `import.meta.url` to determine the source file location.
 * @param component The component to be rendered in the demo.
 * @param meta Additional meta for the demo.
 */
export const createDemo = createDemoFactory({
  DemoContentLoading,
  DemoContent,
  fallbackUsesAllVariants: true,
  projectDir,
  projectUrl,
});

/**
 * Creates a demo component for displaying code examples with syntax highlighting.
 * A variant is a different implementation style of the same component.
 * @param url Depends on `import.meta.url` to determine the source file location.
 * @param variants The variants of the component to be rendered in the demo.
 * @param meta Additional meta for the demo.
 */
export const createDemoWithVariants = createDemoWithVariantsFactory({
  DemoContentLoading,
  DemoContent,
  fallbackUsesAllVariants: true,
  projectDir,
  projectUrl,
});

.root {
  background-color: #e5484d !important;
  border-color: #e5484d !important;
}

'use client';

import * as React from 'react';
import type { ContentLoadingProps } from '@mui/internal-docs-infra/CodeHighlighter/types';
import { generateFileSlug } from '@mui/internal-docs-infra/pipeline/loaderUtils';
import { Tabs } from '@/components/Tabs';
import { CodeActionsMenu } from './CodeActionsMenu';
import { CodeBlockHeader, CodeBlockHeaderLabel } from './CodeBlockHeader';
import { DemoVariantBar } from './DemoVariantBar';
import styles from './DemoContent.module.css';
import loadingStyles from './DemoContentLoading.module.css';

import './syntax.css';

const variantNames: Record<string, string | undefined> = {
  CssModules: 'CSS Modules',
};

export function DemoContentLoading(props: ContentLoadingProps<object>) {
  const mainSlug = props.slug ?? '';
  const tabs = React.useMemo(
    () =>
      props.fileNames?.map((name) => ({
        id: name || '',
        name: name || '',
        slug: generateFileSlug(mainSlug, name || '', 'Default'),
      })),
    [props.fileNames, mainSlug],
  );
  const variants = React.useMemo(
    () =>
      Object.keys(props.components || {}).map((variant) => ({
        value: variant,
        label: variantNames[variant] || variant,
      })),
    [props.components],
  );

  const onTabSelect = React.useCallback(() => {
    // Handle tab selection
  }, []);

  const firstFileName = props.fileNames?.[0];
  const showTabs = !!tabs && tabs.length > 1;

  return (
    <div>
      {(props.fileNames || []).map((name) => {
        const slug = generateFileSlug(mainSlug, name, 'Default');
        return <span key={slug} id={slug} className={styles.fileRefs} />;
      })}
      {Object.entries(props.extraVariants || {}).flatMap(([variantName, variant]) =>
        (variant.fileNames || []).map((name) => {
          const slug = generateFileSlug(mainSlug, name, variantName);
          return <span key={slug} id={slug} className={styles.fileRefs} />;
        }),
      )}
      <div className={styles.container}>
        <div className={styles.demoSection}>
          <DemoVariantBar variants={variants} selectedVariant={variants[0]?.value} disabled />
          <div className={styles.demoSurface}>{props.component}</div>
        </div>
        <div className={styles.codeSection}>
          <CodeBlockHeader menu={<CodeActionsMenu loading inline={!showTabs} />}>
            {showTabs && (
              <Tabs tabs={tabs} selectedTabId={firstFileName} onTabSelect={onTabSelect} disabled />
            )}
            {!showTabs && firstFileName && (
              <CodeBlockHeaderLabel>{firstFileName}</CodeBlockHeaderLabel>
            )}
          </CodeBlockHeader>
          <div className={styles.code}>
            <pre className={styles.codeBlock}>{props.source}</pre>
          </div>
          <div className={loadingStyles.extraFiles}>
            {Object.keys(props.extraSource || {}).map((slug) => (
              <pre key={slug}>{props.extraSource?.[slug]}</pre>
            ))}
          </div>
          <div className={loadingStyles.extraVariants}>
            {Object.keys(props.extraVariants || {}).map((slug) => (
              <div key={slug} className={loadingStyles.extraVariant}>
                <span>{slug}</span>
                <pre>
                  {Object.keys(props.extraVariants?.[slug].extraSource || {}).map((key) => (
                    <div key={key}>
                      <strong>{key}:</strong> {props.extraVariants?.[slug]?.extraSource?.[key]}
                    </div>
                  ))}
                </pre>
              </div>
            ))}
          </div>
        </div>
      </div>
    </div>
  );
}

'use client';

import * as React from 'react';
import type { ContentProps } from '@mui/internal-docs-infra/CodeHighlighter/types';
import { useDemo } from '@mui/internal-docs-infra/useDemo';
import { Tabs } from '@/components/Tabs';
import { CodeActionsMenu } from './CodeActionsMenu';
import { CodeBlockHeader, CodeBlockHeaderLabel } from './CodeBlockHeader';
import { DemoVariantBar } from './DemoVariantBar';
import styles from './DemoContent.module.css';

import './syntax.css';

const variantNames: Record<string, string | undefined> = {
  CssModules: 'CSS Modules',
};

export function DemoContent(props: ContentProps<object>) {
  const demo = useDemo(props, { preClassName: styles.codeBlock });

  const hasJsTransform = demo.availableTransforms.includes('js');
  const isJsSelected = demo.selectedTransform === 'js';

  const toggleJs = React.useCallback(
    (enabled: boolean) => {
      demo.selectTransform(enabled ? 'js' : null);
    },
    [demo],
  );

  const tabs = React.useMemo(
    () => demo.files.map(({ name, slug }) => ({ id: name, name, slug })),
    [demo.files],
  );
  const variants = React.useMemo(
    () =>
      demo.variants.map((variant) => ({ value: variant, label: variantNames[variant] || variant })),
    [demo.variants],
  );

  const hasTabs = tabs.length > 1;

  const selectedFileSlug = React.useMemo(
    () =>
      demo.allFilesSlugs.find(
        (entry) =>
          entry.fileName === demo.selectedFileName && entry.variantName === demo.selectedVariant,
      )?.slug,
    [demo.allFilesSlugs, demo.selectedFileName, demo.selectedVariant],
  );

  return (
    <div>
      {demo.allFilesSlugs.map(({ slug }) => (
        <span key={slug} id={slug} className={styles.fileRefs} />
      ))}
      <div className={styles.container}>
        <div className={styles.demoSection}>
          <DemoVariantBar
            variants={variants}
            selectedVariant={demo.selectedVariant}
            onVariantChange={demo.selectVariant}
          />
          <div className={styles.demoSurface}>{demo.component}</div>
        </div>
        <div className={styles.codeSection}>
          <CodeBlockHeader
            menu={
              <CodeActionsMenu
                inline={!hasTabs}
                onCopy={demo.copy}
                onCopyMarkdown={hasTabs ? demo.copyMarkdown : undefined}
                fileUrl={demo.selectedFileUrl}
                fileName={demo.selectedFileName}
                fileSlug={selectedFileSlug}
                jsTransform={
                  hasJsTransform ? { enabled: isJsSelected, onToggle: toggleJs } : undefined
                }
              />
            }
          >
            {hasTabs ? (
              <Tabs
                tabs={tabs}
                selectedTabId={demo.selectedFileName}
                onTabSelect={demo.selectFileName}
              />
            ) : (
              <CodeBlockHeaderLabel>{demo.selectedFileName}</CodeBlockHeaderLabel>
            )}
          </CodeBlockHeader>
          <div className={styles.code}>{demo.selectedFile}</div>
        </div>
      </div>
    </div>
  );
}

'use client';

import * as React from 'react';
import { Menu } from '@base-ui/react/menu';
import { Select } from '@/components/Select';
import { LabeledSwitch } from '@/components/LabeledSwitch';
import styles from './CodeActionsMenu.module.css';

export interface CodeActionsMenuProps {
  onCopy?: (event: React.MouseEvent<Element>) => void | Promise<void>;
  /**
   * Copies all files in the current variant as a Markdown snippet (heading
   * + per-file fenced code blocks). Provide only on multi-file demos and
   * code blocks; single-file callers should leave this `undefined`.
   */
  onCopyMarkdown?: (event: React.MouseEvent<Element>) => void | Promise<void>;
  fileUrl?: string;
  fileName?: string;
  /**
   * Slug used to build a deep link to this file inside the current page.
   * When provided, a "Copy link" action is shown that copies
   * `${location.origin}${location.pathname}#${fileSlug}` to the clipboard.
   */
  fileSlug?: string;
  /**
   * Resets edits made to the source. When provided, a "Reset edits" action is
   * shown. Pass `undefined` (the typical case for non-editable demos and code
   * blocks) to hide the action.
   */
  onReset?: () => void;
  jsTransform?: {
    enabled: boolean;
    onToggle: (enabled: boolean) => void;
  };
  variants?: {
    items: { label: string; value: string }[];
    selected?: string;
    onChange: (value: string) => void;
  };
  /**
   * Render actions as a row of icon buttons in the header instead of as a
   * popup menu. Use for single-file code blocks where there's plenty of
   * horizontal room. The same icons are used in both modes.
   */
  inline?: boolean;
  loading?: boolean;
}

export function CodeActionsMenu({
  onCopy,
  onCopyMarkdown,
  fileUrl,
  fileName,
  fileSlug,
  onReset,
  jsTransform,
  variants,
  inline,
  loading,
}: CodeActionsMenuProps) {
  const handleCopyLink = React.useCallback(() => {
    if (!fileSlug || typeof window === 'undefined') {
      return;
    }
    const link = `${window.location.origin}${window.location.pathname}#${fileSlug}`;
    void navigator.clipboard?.writeText(link);
  }, [fileSlug]);
  // Hide the GitHub link when the URL is a local `file://` URL — that means
  // the build-time URL rewrite was skipped (e.g. for server-loaded demos) and
  // the link wouldn't be navigable from the browser.
  const externalFileUrl = fileUrl && !fileUrl.startsWith('file://') ? fileUrl : undefined;
  if (inline) {
    if (loading) {
      return (
        <div className={styles.inlineActions}>
          {jsTransform && (
            <button
              type="button"
              className={styles.inlineIconButton}
              aria-label="Toggle JavaScript"
              disabled
            >
              <CheckIcon />
            </button>
          )}
          <button type="button" className={styles.inlineIconButton} aria-label="Copy code" disabled>
            <CopyIcon />
          </button>
        </div>
      );
    }
    return (
      <div className={styles.inlineActions}>
        {variants && variants.items.length > 1 && (
          <Select
            items={variants.items}
            value={variants.selected}
            onValueChange={(value) => value && variants.onChange(value)}
          />
        )}
        {jsTransform && (
          <LabeledSwitch
            checked={jsTransform.enabled}
            onCheckedChange={jsTransform.onToggle}
            labels={{ false: 'TS', true: 'JS' }}
          />
        )}
        {onCopy && (
          <InlineIconButton
            onClick={onCopy}
            label={fileName ? `Copy ${fileName} source` : 'Copy source'}
            icon={<CopyIcon />}
          />
        )}
        {fileSlug && (
          <InlineIconButton
            onClick={handleCopyLink}
            label={fileName ? `Copy ${fileName} link` : 'Copy link'}
            icon={<LinkIcon />}
          />
        )}
        {onReset && <InlineIconButton onClick={onReset} label="Reset edits" icon={<ResetIcon />} />}
        {externalFileUrl && (
          <a
            className={styles.inlineIconButton}
            href={externalFileUrl}
            target="_blank"
            rel="noreferrer noopener"
            aria-label={fileName ? `Open ${fileName} in GitHub` : 'Open in GitHub'}
          >
            <GitHubIcon />
          </a>
        )}
        {onCopyMarkdown && (
          <InlineIconButton
            onClick={onCopyMarkdown}
            label="Copy all files as Markdown"
            icon={<MarkdownIcon />}
          />
        )}
      </div>
    );
  }

  const handleCopy = (event: React.MouseEvent<Element>) => {
    onCopy?.(event);
  };

  const handleCopyMarkdown = (event: React.MouseEvent<Element>) => {
    onCopyMarkdown?.(event);
  };

  if (loading) {
    return (
      <button type="button" className={styles.menuTrigger} aria-label="More actions" disabled>
        <span className={styles.menuTriggerInner}>
          <MoreIcon />
        </span>
      </button>
    );
  }

  return (
    <Menu.Root>
      <Menu.Trigger className={styles.menuTrigger} aria-label="More actions" type="button">
        <span className={styles.menuTriggerInner}>
          <MoreIcon />
        </span>
      </Menu.Trigger>
      <Menu.Portal>
        <Menu.Positioner sideOffset={8} align="end" alignOffset={2} arrowPadding={3}>
          <Menu.Popup className={styles.menuPopup}>
            <Menu.Arrow className={styles.menuArrow}>
              <ArrowIcon />
            </Menu.Arrow>
            {onCopy && (
              <Menu.Item className={styles.menuItem} onClick={handleCopy}>
                <span className={styles.menuItemIcon} aria-hidden>
                  <CopyIcon />
                </span>
                {fileName ? `Copy ${fileName} source` : 'Copy source'}
              </Menu.Item>
            )}
            {fileSlug && (
              <Menu.Item className={styles.menuItem} onClick={handleCopyLink}>
                <span className={styles.menuItemIcon} aria-hidden>
                  <LinkIcon />
                </span>
                {fileName ? `Copy ${fileName} link` : 'Copy link'}
              </Menu.Item>
            )}
            {onReset && (
              <Menu.Item className={styles.menuItem} onClick={onReset}>
                <span className={styles.menuItemIcon} aria-hidden>
                  <ResetIcon />
                </span>
                Reset edits
              </Menu.Item>
            )}
            {externalFileUrl && (
              <Menu.Item
                className={styles.menuItem}
                render={
                  <a href={externalFileUrl} target="_blank" rel="noreferrer noopener">
                    <span className={styles.menuItemIcon} aria-hidden>
                      <GitHubIcon />
                    </span>
                    {fileName ? `Open ${fileName} in GitHub` : 'Open in GitHub'}
                  </a>
                }
                closeOnClick
              />
            )}
            {onCopyMarkdown && (
              <Menu.Item className={styles.menuItem} onClick={handleCopyMarkdown}>
                <span className={styles.menuItemIcon} aria-hidden>
                  <MarkdownIcon />
                </span>
                Copy all files as Markdown
              </Menu.Item>
            )}
            {jsTransform && (
              <React.Fragment>
                <div className={styles.menuSeparator} role="separator" />
                <Menu.CheckboxItem
                  className={styles.menuItem}
                  checked={jsTransform.enabled}
                  onCheckedChange={jsTransform.onToggle}
                  closeOnClick={false}
                >
                  <span className={styles.menuItemIcon} aria-hidden>
                    {jsTransform.enabled ? <CheckIcon /> : null}
                  </span>
                  Transpile to JavaScript
                </Menu.CheckboxItem>
              </React.Fragment>
            )}
            {variants && variants.items.length > 1 && (
              <React.Fragment>
                <div className={styles.menuSeparator} role="separator" />
                <Menu.RadioGroup value={variants.selected} onValueChange={variants.onChange}>
                  {variants.items.map((item) => (
                    <Menu.RadioItem
                      key={item.value}
                      value={item.value}
                      className={styles.menuItem}
                      closeOnClick
                    >
                      <span className={styles.menuItemIcon} aria-hidden>
                        <Menu.RadioItemIndicator>
                          <CheckIcon />
                        </Menu.RadioItemIndicator>
                      </span>
                      {item.label}
                    </Menu.RadioItem>
                  ))}
                </Menu.RadioGroup>
              </React.Fragment>
            )}
          </Menu.Popup>
        </Menu.Positioner>
      </Menu.Portal>
    </Menu.Root>
  );
}

function InlineIconButton({
  onClick,
  label,
  icon,
}: {
  onClick: (event: React.MouseEvent<HTMLButtonElement>) => void | Promise<void>;
  label: string;
  icon: React.ReactNode;
}) {
  return (
    <button type="button" className={styles.inlineIconButton} onClick={onClick} aria-label={label}>
      {icon}
    </button>
  );
}

function MoreIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="16" height="20" viewBox="0 0 16 20" fill="currentColor" {...props}>
      <circle cx="8" cy="2" r="2" />
      <circle cx="8" cy="10" r="2" />
      <circle cx="8" cy="18" r="2" />
    </svg>
  );
}

function CopyIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" {...props}>
      <path
        d="M16 1H4C2.9 1 2 1.9 2 3V17H4V3H16V1ZM19 5H8C6.9 5 6 5.9 6 7V21C6 22.1 6.9 23 8 23H19C20.1 23 21 22.1 21 21V7C21 5.9 20.1 5 19 5ZM19 21H8V7H19V21Z"
        fill="currentColor"
      />
    </svg>
  );
}

function LinkIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" {...props}>
      <path
        d="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7c-2.76 0-5 2.24-5 5s2.24 5 5 5h4v-1.9H7c-1.71 0-3.1-1.39-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.71 0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4c2.76 0 5-2.24 5-5s-2.24-5-5-5z"
        fill="currentColor"
      />
    </svg>
  );
}

function ResetIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" {...props}>
      <path
        d="M12 5V2L7 7l5 5V8c3.31 0 6 2.69 6 6s-2.69 6-6 6-6-2.69-6-6H4c0 4.42 3.58 8 8 8s8-3.58 8-8-3.58-8-8-8z"
        fill="currentColor"
      />
    </svg>
  );
}

function MarkdownIcon(props: React.ComponentProps<'svg'>) {
  // GitHub's Markdown mark, simplified.
  return (
    <svg width="16" height="12" viewBox="0 0 208 128" fill="currentColor" {...props}>
      <path
        fillRule="evenodd"
        clipRule="evenodd"
        d="M193 0H15C6.7 0 0 6.7 0 15v98c0 8.3 6.7 15 15 15h178c8.3 0 15-6.7 15-15V15c0-8.3-6.7-15-15-15zM30 98V30h20l20 25 20-25h20v68H90V59L70 84 50 59v39H30zm125 0l-30-33h20V30h20v35h20l-30 33z"
      />
    </svg>
  );
}

function GitHubIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="14" height="14" viewBox="0 0 16 16" fill="currentColor" {...props}>
      <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z" />
    </svg>
  );
}

function CheckIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="12" height="12" viewBox="0 0 10 10" fill="currentColor" {...props}>
      <path d="M9.1603 1.12218C9.50684 1.34873 9.60427 1.81354 9.37792 2.16038L5.13603 8.66012C5.01614 8.8438 4.82192 8.96576 4.60451 8.99384C4.3871 9.02194 4.1683 8.95335 4.00574 8.80615L1.24664 6.30769C0.939709 6.02975 0.916013 5.55541 1.19372 5.24822C1.47142 4.94102 1.94536 4.91731 2.2523 5.19524L4.36085 7.10461L8.12299 1.33999C8.34934 0.993152 8.81376 0.895638 9.1603 1.12218Z" />
    </svg>
  );
}

function ArrowIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="20" height="10" viewBox="0 0 20 10" fill="none" {...props}>
      <path
        d="M9.66437 2.60207L4.80758 6.97318C4.07308 7.63423 3.11989 8 2.13172 8H0V10H20V8H18.5349C17.5468 8 16.5936 7.63423 15.8591 6.97318L11.0023 2.60207C10.622 2.2598 10.0447 2.25979 9.66437 2.60207Z"
        className={styles.arrowFill}
      />
      <path
        d="M8.99542 1.85876C9.75604 1.17425 10.9106 1.17422 11.6713 1.85878L16.5281 6.22989C17.0789 6.72568 17.7938 7.00001 18.5349 7.00001L15.89 7L11.0023 2.60207C10.622 2.2598 10.0447 2.2598 9.66436 2.60207L4.77734 7L2.13171 7.00001C2.87284 7.00001 3.58774 6.72568 4.13861 6.22989L8.99542 1.85876Z"
        className={styles.arrowOuterStroke}
      />
      <path
        d="M10.3333 3.34539L5.47654 7.71648C4.55842 8.54279 3.36693 9 2.13172 9H0V8H2.13172C3.11989 8 4.07308 7.63423 4.80758 6.97318L9.66437 2.60207C10.0447 2.25979 10.622 2.2598 11.0023 2.60207L15.8591 6.97318C16.5936 7.63423 17.5468 8 18.5349 8H20V9H18.5349C17.2998 9 16.1083 8.54278 15.1901 7.71648L10.3333 3.34539Z"
        className={styles.arrowInnerStroke}
      />
    </svg>
  );
}

import * as React from 'react';
import styles from './CodeBlockHeader.module.css';

export interface CodeBlockHeaderProps {
  /**
   * Main header content (typically a `<Tabs>` element or a filename label).
   */
  children?: React.ReactNode;
  /**
   * Right-aligned action slot — typically a `<CodeActionsMenu>`.
   */
  menu?: React.ReactNode;
  /**
   * When true, the side decoration lines start 8px below the top edge so they
   * clear a rounded container corner. Use for standalone code blocks where the
   * header sits at the top of a rounded container; leave false for demo code
   * sections that have a sibling above.
   */
  roundedTop?: boolean;
}

/**
 * Shared 48px-tall header used at the top of code blocks and demo code sections.
 * Renders the border chrome and an optional menu slot that overflows 8px past
 * the right edge of the container.
 */
export function CodeBlockHeader({ children, menu, roundedTop }: CodeBlockHeaderProps) {
  return (
    <div className={styles.header}>
      <div
        className={`${styles.headerContainer} ${roundedTop ? styles.headerContainerRoundedTop : ''}`}
      >
        <div className={styles.tabContainer}>{children}</div>
        {menu}
      </div>
    </div>
  );
}

/**
 * A filename / static label rendered inside `<CodeBlockHeader>` when there
 * are no tabs. Matches the typography of the tab labels.
 */
export function CodeBlockHeaderLabel({ children }: { children: React.ReactNode }) {
  return <span className={styles.label}>{children}</span>;
}

import * as React from 'react';
import { Select } from '@/components/Select';
import styles from './DemoVariantBar.module.css';

export interface DemoVariantBarProps {
  variants: { label: string; value: string }[];
  selectedVariant?: string;
  onVariantChange?: (value: string | null) => void;
  disabled?: boolean;
}

/**
 * Variant selector pinned to the top-left of a demo section.
 * Renders nothing when there are fewer than two variants.
 */
export function DemoVariantBar({
  variants,
  selectedVariant,
  onVariantChange,
  disabled,
}: DemoVariantBarProps) {
  if (variants.length < 2) {
    return null;
  }
  return (
    <div className={styles.variantBar}>
      <Select
        items={variants}
        value={selectedVariant}
        onValueChange={onVariantChange}
        disabled={disabled}
        className={styles.variantSelect}
      />
    </div>
  );
}

.container {
  border: 1px solid #d0cdd7;
  border-radius: 8px;
}

.demoSection {
  position: relative;
  border-radius: 7px 7px 0 0;
}

.demoSurface {
  padding: 24px;
}

.codeSection {
  border-top: 1px solid #d0cdd7;
}

.code {
  padding: 10px 0;
}

.codeBlock {
  tab-size: 2;
  margin: 0;
  padding: 6px 0;
  overflow-x: auto;
}

/* Code element inside pre — block so frames stretch to the widest line */
.codeBlock :global(code) {
  display: block;
  min-width: fit-content;
}

.codeBlock :global(.frame) {
  display: block;
  padding: 0 12px;
}

.codeBlock :global(.frame[data-lined]) {
  display: block;
  white-space: normal;
  line-height: 0;
}

.codeBlock :global(.frame[data-lined] .line) {
  display: block;
  white-space: pre;
  line-height: initial;
}

/* Highlighted frames get rounded corners and background */
.codeBlock :global(.frame[data-frame-type='highlighted']),
.codeBlock :global(.frame[data-frame-type='highlighted-unfocused']) {
  background: #ebe4ff;
  border-radius: 8px;
  margin: 0 6px;
  padding: 0 6px;
}

/* Line-level highlight inside a frame (nested emphasis) */
.codeBlock :global(.line[data-hl]) {
  background: #ebe4ff;
  margin: 0 -6px;
  padding: 0 6px;
}

.codeBlock :global(mark) {
  background: #ebe4ff;
  border-radius: 4px;
}

.codeBlock :global(mark[data-hl]) {
  background: #e1d9ff;
}

.codeBlock :global(mark[data-hl='strong']) {
  background: #d4c8ff;
}

.codeBlock :global(.line[data-hl='strong']) {
  background: #e1d9ff;
  margin: 0 -6px;
  padding: 0 6px;
}

/* Only strong lines bordering a regular highlight line need to stack above
   it (so the regular line's extended background sits underneath the strong
   line's rounded corners). */
.codeBlock :global(.line[data-hl='strong'][data-hl-position='single']),
.codeBlock :global(.line[data-hl='strong'][data-hl-position='end']) {
  position: relative;
  z-index: 1;
}

/* Visually merge a regular highlighted line into an adjacent strong block by
   extending its background through the gap between lines. */
.codeBlock :global(.line[data-hl='']:has(+ .line[data-hl='strong'])) {
  padding-bottom: 6px;
  margin-bottom: -6px;
}

.codeBlock :global(.line[data-hl='strong'] + .line[data-hl='']) {
  padding-top: 6px;
  margin-top: -6px;
}

.codeBlock :global(.line[data-hl-position='single']) {
  border-radius: 8px;
}

.codeBlock :global(.line[data-hl-position='start']) {
  border-top-left-radius: 8px;
  border-top-right-radius: 8px;
}

.codeBlock :global(.line[data-hl-position='end']) {
  border-bottom-left-radius: 8px;
  border-bottom-right-radius: 8px;
}

.codeBlock :global(.line[data-hl-description])::after {
  content: attr(data-hl-description);
  float: right;
  background: #8145b5;
  border-radius: 8px;
  color: white;
  padding: 2px 4px;
  margin-right: -6px;
}

.codeBlock :global(.frame[data-frame-description])::before {
  content: attr(data-frame-description);
  float: right;
  background: #8145b5;
  border-radius: 8px;
  color: white;
  padding: 2px 4px;
}

.extraFiles {
  display: none;
}

.extraVariants {
  display: none;
}

@import '@wooorm/starry-night/style/light' layer(starry-night);

:root {
  --color-docs-infra-syntax-number: #0550ae;
  --color-docs-infra-syntax-boolean: #0550ae;
  --color-docs-infra-syntax-nullish: #59636e;
  --color-docs-infra-syntax-property-string: #0550ae;
  --color-docs-infra-syntax-object-property: #0550ae;
  --color-docs-infra-syntax-attr-key: #0550ae;
  --color-docs-infra-syntax-attr-value: #0a3069;
  --color-docs-infra-syntax-attr-equals: #24292f;
  --color-docs-infra-syntax-data-attr: #0550ae;
  --color-docs-infra-syntax-css-property: #0550ae;
  --color-docs-infra-syntax-css-value: #0550ae;
  --color-docs-infra-syntax-this: #cf222e;
  --color-docs-infra-syntax-builtin-type: #0550ae;
  --color-docs-infra-syntax-punctuation: #24292f;
  --color-docs-infra-syntax-jsx: #116329;
  --color-docs-infra-syntax-jsx-variable: #953800;
  --color-docs-infra-syntax-html-tag: #0550ae;
  --color-docs-infra-syntax-jsx-tag: #116329;
}

.di-num {
  color: var(--color-docs-infra-syntax-number);
}

.di-bool {
  color: var(--color-docs-infra-syntax-boolean);
}

.di-n {
  color: var(--color-docs-infra-syntax-nullish);
}

.di-ps {
  color: var(--color-docs-infra-syntax-property-string);
}

.di-op {
  color: var(--color-docs-infra-syntax-object-property);
}

.di-ak {
  color: var(--color-docs-infra-syntax-attr-key);
}

.di-av {
  color: var(--color-docs-infra-syntax-attr-value);
}

.di-ae {
  color: var(--color-docs-infra-syntax-attr-equals);
}

.di-da {
  color: var(--color-docs-infra-syntax-data-attr);
}

.di-cp {
  color: var(--color-docs-infra-syntax-css-property);
}

.di-cv {
  color: var(--color-docs-infra-syntax-css-value);
}

.di-this {
  color: var(--color-docs-infra-syntax-this);
}

.di-bt {
  color: var(--color-docs-infra-syntax-builtin-type);
}

.di-pu {
  color: var(--color-docs-infra-syntax-punctuation);
}

.di-jsx {
  color: var(--color-docs-infra-syntax-jsx);
}

.di-jv {
  color: var(--color-docs-infra-syntax-jsx-variable);
}

.di-ht {
  color: var(--color-docs-infra-syntax-html-tag);
}

.di-jt {
  color: var(--color-docs-infra-syntax-jsx-tag);
}

code[data-inline] .pl-smi {
  color: inherit;
}

.menuTrigger {
  flex: 0 0 28px;
  box-sizing: border-box;
  /* The visible 20px ellipse keeps its position; 4px of padding overflows
     into surrounding space on each side to grow the tap target to 28px,
     and the negative margins absorb that padding so layout is unchanged. */
  margin-top: -1px;
  margin-right: -24px;
  margin-left: -4px;
  width: 28px;
  height: 49px;
  padding: 0 4px;
  display: flex;
  align-items: center;
  justify-content: center;
  border: 0;
  background: transparent;
  z-index: 10;
  color: #65636d;
  cursor: pointer;
}

.menuTriggerInner {
  display: flex;
  align-items: center;
  justify-content: center;
  width: 100%;
  height: 100%;
  border: 1px solid transparent;
  border-radius: 0 4px 4px 0;
  background: transparent;
  transition:
    background-color 0.2s ease,
    border-color 0.2s ease;
}

.menuTrigger:hover:not(:disabled) .menuTriggerInner {
  background-color: #f2eff3;
  border-color: #d0cdd7;
}

.menuTrigger:active:not(:disabled) .menuTriggerInner,
.menuTrigger[data-popup-open] .menuTriggerInner {
  background-color: #eae7ef;
  border-color: #d0cdd7;
}

.menuTrigger:focus-visible {
  outline: 0;
}

.menuTrigger:focus-visible .menuTriggerInner {
  outline: 2px solid #8e4ec6;
  outline-offset: 0;
}

.menuTrigger:disabled {
  cursor: default;
  opacity: 0.6;
}

.menuPopup {
  box-sizing: border-box;
  min-width: 160px;
  padding: 4px;
  border-radius: 4px;
  background-color: canvas;
  outline: 1px solid #d0cdd7;
  box-shadow:
    0 10px 15px -3px #d0cdd7,
    0 4px 6px -4px #d0cdd7;
  color: #65636d;
  font-size: 0.875rem;
  transform-origin: var(--transform-origin);
  transition:
    transform 150ms,
    opacity 150ms;
}

.menuPopup[data-starting-style],
.menuPopup[data-ending-style] {
  opacity: 0;
  transform: scale(0.95);
}

.menuArrow {
  display: flex;
}

.menuArrow[data-side='top'] {
  bottom: -8px;
  rotate: 180deg;
}

.menuArrow[data-side='bottom'] {
  top: -8px;
  rotate: 0deg;
}

.menuArrow[data-side='left'] {
  right: -13px;
  rotate: 90deg;
}

.menuArrow[data-side='right'] {
  left: -13px;
  rotate: -90deg;
}

.arrowFill {
  fill: canvas;
}

.arrowOuterStroke {
  fill: #d0cdd7;
}

.arrowInnerStroke {
  fill: none;
}

.menuItem,
.menuItem:link,
.menuItem.menuItem:visited {
  display: flex;
  align-items: center;
  gap: 8px;
  padding: 6px 10px;
  border-radius: 6px;
  outline: 0;
  cursor: default;
  user-select: none;
  color: inherit;
  text-decoration: none;
}

.menuItem[data-highlighted] {
  background-color: #f2eff3;
}

.menuItemIcon {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 14px;
  height: 14px;
  flex: 0 0 14px;
  color: #65636d;
}

.menuSeparator {
  height: 1px;
  margin: 4px 6px;
  background-color: #d0cdd7;
}

/* Inline mode — row of icon buttons in the header */
.inlineActions {
  display: flex;
  align-items: center;
  gap: 4px;
  padding-right: 8px;
  height: 48px;
}

.inlineIconButton,
.inlineIconButton:link,
.inlineIconButton.inlineIconButton:visited {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 28px;
  height: 28px;
  padding: 0;
  border: 1px solid transparent;
  border-radius: 4px;
  background: transparent;
  color: #65636d;
  cursor: pointer;
  text-decoration: none;
  transition:
    background-color 0.2s ease,
    border-color 0.2s ease;
}

.inlineIconButton:hover {
  background-color: #f2eff3;
  border-color: #d0cdd7;
}

.inlineIconButton:active {
  background-color: #eae7ef;
  border-color: #d0cdd7;
}

.inlineIconButton:focus-visible {
  outline: 2px solid #8e4ec6;
  outline-offset: 1px;
}

.header {
  border-bottom: 1px solid #d0cdd7;
  height: 48px;
  position: relative;
}

.headerContainer {
  position: absolute;
  width: 100%;
  display: flex;
}

/* 1px vertical lines that overlap the parent container's border so the
   tabContainer can extend `margin: -1px` past the rounded corners without
   exposing a gap. */
.headerContainer::before {
  content: '';
  position: absolute;
  top: 0;
  left: 0;
  bottom: 0;
  width: 1px;
  margin: -1px;
  background-color: #d0cdd7;
}

.headerContainer::after {
  content: '';
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  width: 1px;
  margin: -1px;
  background-color: #d0cdd7;
}

.headerContainerRoundedTop::before,
.headerContainerRoundedTop::after {
  top: 8px;
  margin-top: 0;
}

.tabContainer {
  flex: 1 1 auto;
  display: flex;
  align-items: center;
  gap: 8px;
  margin-left: -1px;
  margin-right: -1px;
  padding-bottom: 2px;
  overflow-x: auto;
}

/* Filename / label inside the header (when no tabs are rendered). */
.label {
  display: flex;
  align-items: center;
  height: 48px;
  padding: 0 12px;
  color: #65636d;
  font-size: 12px;
  font-family: var(--font-code);
}

.variantBar {
  display: flex;
}

/* Variant trigger inside the demo bar — strips its top and left borders so
   the demo container's border doubles as the selector's top and left edges.
   The top-left corner is rounded to match the container's outer rounding,
   and the bottom-right is rounded so the trigger reads as its own chip. */
.variantSelect {
  border-top: 0;
  border-left: 0;
  border-radius: 7px 0 8px;
  padding-top: 2px;
}

Demo Server Loaded

For more dynamic use cases, you can load code content from external sources or APIs at runtime:

Note

This example uses React Server Components (RSC) to load and parse files at request time instead of relying on the webpack loader for build-time precomputation. This approach is recommended when rendering based on dynamic routes (like app/components/[component].tsx) where the content isn't known at build time. In these scenarios, you'd typically use the <CodeHighlighter> component directly rather than the factory pattern with createDemo().

Checkbox

import * as React from 'react';
import { Checkbox } from '@/components/Checkbox';

export function CheckboxBasic() {
  return (
    // @focus
    <Checkbox defaultChecked />
  );
}

import { createDemo } from './createDemo';
import { CheckboxBasic } from './CheckboxBasic';

export const DemoCheckboxBasic = createDemo(import.meta.url, CheckboxBasic, {
  skipPrecompute: true,
});

ExpandCollapse

Client-Side Rendering

CodeHighlighter can also be used on the client side, allowing you to load and parse code dynamically without server-side rendering. This is useful for applications that fetch code from APIs or databases.

You can do so by using the CodeProvider component, which provides the necessary context for CodeHighlighter to function correctly on the client.

Controlled Code Scenarios

CodeHighlighter also supports controlled scenarios where you need to manage code state externally. This is useful for interactive demos where code changes affect other parts of your application or when you need to synchronize code across multiple components.

You can use the CodeControllerContext for this purpose, which provides a controlled environment for managing code state in interactive scenarios.

Authoring Recommendations

Component Name

Demos are exported as Demo${componentName}${demoName} e.g. DemoCheckboxBasic This makes it easy to import a demo by simply typing <DemoCheckbox, and your IDE should display a list of existing demos to auto-import.

Demo Titles

We recommend exporting a Title component attached within your createDemo() factory. This allows us to use an automatically generated title and slug from the URL of the demo index. This ensures that the link for the title is consistent with links to files within the demo itself.

e.g. ./app/components/checkbox/demos/advanced-keyboard/index.ts would generate a title of Advanced Keyboard and a slug of advanced-keyboard. The URL for this demo would be /components/checkbox#advanced-keyboard and a file within it could be /components/checkbox#advanced-keyboard:file.ts.

Also, when MDX is rendered in GitHub, <DemoCheckboxAdvancedKeyboard.Title /> will be visible on the page because it contains the dot. The import is also visible, so readers on GitHub will see this in the place of a demo:

import { DemoCheckboxAdvancedKeyboard } from './demos/advanced-keyboard';

<DemoCheckboxAdvancedKeyboard.Title />

Description of the demo.

If this convention isn't followed, URLs might deviate e.g. /components/checkbox#advanced-keyboard might not link to the correct demo.

// This is not recommended
import { DemoCheckboxAdvancedKeyboard } from './demos/advanced-keyboard'

### An Advanced Keyboard Demo

Description of the demo.

<DemoCheckboxAdvancedKeyboard />

This would result in the URL becoming /components/checkbox#an-advanced-keyboard-demo, and the file URL being /components/checkbox#advanced-keyboard:file.ts, which is not expected.

Descriptions

The description should be a short, concise explanation of what the demo does or why it shows a useful case. It is located directly in the component's docs because it can have rich contents like links, images, or other components. Try to avoid referring directly to the demo itself as when viewing the raw markdown, users won't see the code or renderings from the demo. Ideally, the reader can picture the demo in their mind without needing to see it.

Link to Demo

Include a "See Demo" link after each demo component to allow users to navigate directly to the demo's source directory. This is especially useful when viewing the documentation in markdown editors or GitHub, where users can click the link to browse the demo files.

The link should point to the demo's directory using a relative path:

<DemoCheckboxBasic />

[See Demo](./demos/basic/)

This pattern makes it easy for developers to explore the demo's implementation, understand the file structure, and reference the source code when building their own components.

Separators

Use horizontal rules (---) to separate different sections of the demo. This allows the description of the previous demo to be visually distinct from the next demo.

import { DemoCheckboxBasic } from './demos/basic';

<DemoCheckboxBasic.Title />

Description of the basic demo.

<DemoCheckboxBasic />

[See Demo](./demos/basic/)

---

import { DemoCheckboxAdvanced } from './demos/second-demo';

<DemoCheckboxAdvanced.Title />

Description of the second demo.

<DemoCheckboxAdvanced />

[See Demo](./demos/second-demo/)

Within GitHub, it will display like this without rendering the demo and with See Demo underlined:

import { DemoCheckboxBasic } from './demos/basic';

<DemoCheckboxBasic.Title />

Description of the basic demo.

See Demo

---

import { DemoCheckboxAdvanced } from './demos/advanced';

<DemoCheckboxAdvanced.Title />

Description of the advanced demo.

See Demo

Tip

For Documentation Tooling: If you're building tooling to render these demos in a web interface, you can use a remark plugin to automatically remove the "See Demo" links and horizontal rule separators (---) from the rendered output, since the interactive demos provide their own navigation. See the transformMarkdownMetaLinks plugin documentation for implementation details.

Benchmarking

For performance benchmarks of the CodeHighlighter component, see the Benchmarking Code Highlighter page.

Build-Time vs Server Rendering vs Client Rendering

Note

The CodeControllerContext works with all three rendering methods.

When rendering a code block, the user should consider the following options based on their use case:

Build-Time (Recommended)

Use the factory pattern optimal performance:

Advantages:

✓ Faster initial load times
✓ Isomorphic rendering support
✓ Automatic caching based on dependencies for each demo

Requirements:

Must use createDemo() in index.ts files
Must be in a demo directory structure

Server Rendering

Use direct CodeHighlighter for dynamic content:

Advantages:

✓ Works with dynamic content
✓ Flexible component structure
✓ Can still benefit from the page level cache

Trade-offs:

× Slower initial rendering
× No per-demo build-time cache
× Can only be used within a Server Component

Client Rendering

Use CodeHighlighter on the client with CodeProvider:

Advantages:

✓ Works with dynamic content fetched on the client
✓ Doesn't require an API or server-side rendering
✓ Can be used anywhere in the app
✓ Flexible component structure

Trade-offs:

× Slower initial rendering
× Requires loading and highlighting functions to be bundled
x No automatic caching

Best Practices

Use precompute for static content - Enables a per-demo cache for faster builds
Implement proper loading states - Provide ContentLoading for quicker hydration
Handle errors gracefully - Use ErrorHandler to display meaningful error messages
Optimize highlight timing - Use highlightAfter: 'idle' for non-critical code blocks
Group related variants - Keep related code variations together

Troubleshooting

Common Issues

Code not highlighting:

Ensure sourceParser is provided
Check that the code variant exists
Verify highlightAfter timing is appropriate

Loading states not showing:

Provide ContentLoading component
Use highlightAfter: 'stream' for loading states
Check fallbackUsesExtraFiles settings

Performance issues:

Use demo factory pattern for build-time optimization
Consider highlightAfter: 'idle' for non-critical code
Implement proper error boundaries
Remember: precomputation only works with createDemo() in index.ts files

Precomputation not working:

Ensure you're using createDemo() in an index.ts file
Verify the file is in the correct path pattern: './app/**/demos/*/index.ts'
Make sure the webpack loader is configured correctly

Variants not switching:

Verify variant names match between components and variants
Check that source transformers are configured correctly
Ensure controlled mode is set up properly if needed

Shape

CodeHighlighter

Prop	Type	Description
name	`string \| undefined`	Display name for the code example, used for identification and titles
Content	`React.ComponentType<ContentProps<{}>>`	Component to render the code content and preview
ContentLoading	`\| React.ComponentType<ContentLoadingProps<{}>> \| undefined`	Component to show while code is being loaded or processed
code	`Code \| undefined`	Static code content with variants and metadata
components	`Components \| undefined`	React components for live preview alongside code
contentProps	`{} \| undefined`	Additional props passed to the Content component
controlled	`boolean \| undefined`	Enable controlled mode for external code state management
defaultVariant	`string \| undefined`	Fallback variant when the requested variant is not available
deferParsing	`'none' \| 'json' \| 'gzip' \| undefined`	Defer parsing and populating the AST into memory until the code is enhanced Applies only in production when RSC loading
enhanceAfter	`\| 'init' \| 'stream' \| 'hydration' \| 'idle' \| undefined`	When to enhance the code display with interactivity
fallbackUsesAllVariants	`boolean \| undefined`	Whether fallback content should include all variants
fallbackUsesExtraFiles	`boolean \| undefined`	Whether fallback content should include extra files
fileName	`string \| undefined`	Currently selected file name
forceClient	`boolean \| undefined`	Force client-side rendering even when server rendering is available
globalsCode	`(string \| Code)[] \| undefined`	Global static code snippets to inject, typically for styling or tooling
highlightAfter	`\| 'init' \| 'stream' \| 'hydration' \| 'idle' \| undefined`	When to perform syntax highlighting and code processing
initialVariant	`string \| undefined`	Default variant to show on first load
language	`string \| undefined`	Language for syntax highlighting (e.g., ‘tsx’, ‘css’). When provided, fileName is not required for parsing.
loadCodeMeta	`LoadCodeMeta \| undefined`	Function to load code metadata from a URL
loadSource	`LoadSource \| undefined`	Function to load raw source code and dependencies
loadVariantMeta	`LoadVariantMeta \| undefined`	Function to load specific variant metadata
precompute	`Code \| undefined`	Pre-computed code data from build-time optimization
slug	`string \| undefined`	URL-friendly identifier for deep linking and navigation
sourceEnhancers	`SourceEnhancers \| undefined`	Array of source enhancers that run after parsing to enhance the HAST tree
sourceParser	`Promise<ParseSource> \| undefined`	Promise resolving to a source parser for syntax highlighting
sourceTransformers	`SourceTransformers \| undefined`	Array of source transformers for code processing (e.g., TypeScript to JavaScript)
url	`string \| undefined`	Source URL where the code content originates from
urlPrefix	`{ from: string; to: string } \| undefined`	Optional URL-prefix rewrite forwarded to . Lets the demo factory translate local `file://` URLs returned by `loadSource` into hosted URLs before they reach the client.
variant	`string \| undefined`	Currently selected variant name
variantType	`string \| undefined`	What type of variants are available (e.g., a type `packageManager` when variants `npm` and `yarn` are available)
variants	`string[] \| undefined`	Static variant names that should be fetched at runtime
children	`string \| undefined`	Raw code string for simple use cases

CodeHighlighter Types

These types are available by importing from @mui/internal-docs-infra/CodeHighlighter/types.

BaseContentLoadingProps

type BaseContentLoadingProps = {
  fileNames?: string[];
  source?: React.ReactNode;
  extraSource?: { [fileName: string]: React.ReactNode };
  /** Display name for the code example, used for identification and titles */
  name?: string;
  /** URL-friendly identifier for deep linking and navigation */
  slug?: string;
  /** Source URL where the code content originates from */
  url?: string;
  extraVariants?: Record<string, ContentLoadingVariant>;
}

Code

type Code = { [key: string]: string | VariantCode | undefined }

CodeClientRenderingProps

Client-specific rendering props

type CodeClientRenderingProps = {
  /** The CodeContent component that renders the code display and syntax highlighting */
  children: React.ReactNode;
  /** Loading placeholder shown while code is being processed */
  fallback?: React.ReactNode;
  /** Skip showing fallback content entirely */
  skipFallback?: boolean;
}

CodeContentProps

Core code content and variant management props

type CodeContentProps = {
  /** Static code content with variants and metadata */
  code?: Code;
  /** React components for live preview alongside code */
  components?: Components;
  /** What type of variants are available (e.g., a type `packageManager` when variants `npm` and `yarn` are available) */
  variantType?: string;
  /** Static variant names that should be fetched at runtime */
  variants?: string[];
  /** Currently selected variant name */
  variant?: string;
  /** Currently selected file name */
  fileName?: string;
  /** Language for syntax highlighting (e.g., 'tsx', 'css'). When provided, fileName is not required for parsing. */
  language?: string;
  /** Default variant to show on first load */
  initialVariant?: string;
  /** Fallback variant when the requested variant is not available */
  defaultVariant?: string;
  /** Global static code snippets to inject, typically for styling or tooling */
  globalsCode?: (string | Code)[];
}

CodeFunctionProps

Function props for loading and transforming code

type CodeFunctionProps = {
  /** Function to load code metadata from a URL */
  loadCodeMeta?: LoadCodeMeta;
  /** Function to load specific variant metadata */
  loadVariantMeta?: LoadVariantMeta;
  /** Function to load raw source code and dependencies */
  loadSource?: LoadSource;
  /** Array of source transformers for code processing (e.g., TypeScript to JavaScript) */
  sourceTransformers?: SourceTransformers;
  /** Promise resolving to a source parser for syntax highlighting */
  sourceParser?: Promise<ParseSource>;
  /** Array of source enhancers that run after parsing to enhance the HAST tree */
  sourceEnhancers?: SourceEnhancers;
  /**
   * Optional URL-prefix rewrite forwarded to .
   * Lets the demo factory translate local `file://` URLs returned by
   * `loadSource` into hosted URLs before they reach the client.
   */
  urlPrefix?: { from: string; to: string };
}

CodeHighlighterBaseProps

Base props containing essential properties shared across CodeHighlighter components and helper functions. This serves as the foundation for other CodeHighlighter-related interfaces.

type CodeHighlighterBaseProps<T extends {}> = {
  /** Display name for the code example, used for identification and titles */
  name?: string;
  /** URL-friendly identifier for deep linking and navigation */
  slug?: string;
  /** Source URL where the code content originates from */
  url?: string;
  /** Static code content with variants and metadata */
  code?: Code;
  /** React components for live preview alongside code */
  components?: Components;
  /** What type of variants are available (e.g., a type `packageManager` when variants `npm` and `yarn` are available) */
  variantType?: string;
  /** Static variant names that should be fetched at runtime */
  variants?: string[];
  /** Currently selected variant name */
  variant?: string;
  /** Currently selected file name */
  fileName?: string;
  /** Language for syntax highlighting (e.g., 'tsx', 'css'). When provided, fileName is not required for parsing. */
  language?: string;
  /** Default variant to show on first load */
  initialVariant?: string;
  /** Fallback variant when the requested variant is not available */
  defaultVariant?: string;
  /** Global static code snippets to inject, typically for styling or tooling */
  globalsCode?: (string | Code)[];
  /** Pre-computed code data from build-time optimization */
  precompute?: Code;
  /** Whether fallback content should include extra files */
  fallbackUsesExtraFiles?: boolean;
  /** Whether fallback content should include all variants */
  fallbackUsesAllVariants?: boolean;
  /** Enable controlled mode for external code state management */
  controlled?: boolean;
  /** Raw code string for simple use cases */
  children?: string;
  /**
   * When to perform syntax highlighting and code processing
   * @default 'idle'
   */
  highlightAfter?: 'init' | 'stream' | 'hydration' | 'idle';
  /**
   * When to enhance the code display with interactivity
   * @default 'idle'
   */
  enhanceAfter?: 'init' | 'stream' | 'hydration' | 'idle';
  /** Force client-side rendering even when server rendering is available */
  forceClient?: boolean;
  /**
   * Defer parsing and populating the AST into memory until the code is enhanced
   * Applies only in production when RSC loading
   * @default 'gzip'
   */
  deferParsing?: 'none' | 'json' | 'gzip';
  /** Function to load code metadata from a URL */
  loadCodeMeta?: LoadCodeMeta;
  /** Function to load specific variant metadata */
  loadVariantMeta?: LoadVariantMeta;
  /** Function to load raw source code and dependencies */
  loadSource?: LoadSource;
  /** Array of source transformers for code processing (e.g., TypeScript to JavaScript) */
  sourceTransformers?: SourceTransformers;
  /** Promise resolving to a source parser for syntax highlighting */
  sourceParser?: Promise<ParseSource>;
  /** Array of source enhancers that run after parsing to enhance the HAST tree */
  sourceEnhancers?: SourceEnhancers;
  /**
   * Optional URL-prefix rewrite forwarded to .
   * Lets the demo factory translate local `file://` URLs returned by
   * `loadSource` into hosted URLs before they reach the client.
   */
  urlPrefix?: { from: string; to: string };
  /** Component to render the code content and preview */
  Content: React.ComponentType<ContentProps<T>>;
  /** Additional props passed to the Content component */
  contentProps?: T;
}

CodeHighlighterClientProps

Props for the client-side CodeHighlighter component. Used when rendering happens in the browser with lazy loading and interactive features.

type CodeHighlighterClientProps = {
  /**
   * When to perform syntax highlighting for performance optimization
   * @default 'hydration'
   */
  highlightAfter?: 'init' | 'hydration' | 'idle';
  enhanceAfter?: 'init' | 'hydration' | 'idle';
  /** Display name for the code example, used for identification and titles */
  name?: string;
  /** URL-friendly identifier for deep linking and navigation */
  slug?: string;
  /** Source URL where the code content originates from */
  url?: string;
  /** Static code content with variants and metadata */
  code?: Code;
  /** React components for live preview alongside code */
  components?: Components;
  /** What type of variants are available (e.g., a type `packageManager` when variants `npm` and `yarn` are available) */
  variantType?: string;
  /** Static variant names that should be fetched at runtime */
  variants?: string[];
  /** Currently selected variant name */
  variant?: string;
  /** Currently selected file name */
  fileName?: string;
  /** Language for syntax highlighting (e.g., 'tsx', 'css'). When provided, fileName is not required for parsing. */
  language?: string;
  /** Default variant to show on first load */
  initialVariant?: string;
  /** Fallback variant when the requested variant is not available */
  defaultVariant?: string;
  /** Global static code snippets to inject, typically for styling or tooling */
  globalsCode?: (string | Code)[];
  /** Whether fallback content should include extra files */
  fallbackUsesExtraFiles?: boolean;
  /** Whether fallback content should include all variants */
  fallbackUsesAllVariants?: boolean;
  /** Pre-computed code data from build-time optimization */
  precompute?: Code;
  /** Enable controlled mode for external code state management */
  controlled?: boolean;
  /** Force client-side rendering even when server rendering is available */
  forceClient?: boolean;
  /**
   * Defer parsing and populating the AST into memory until the code is enhanced
   * Applies only in production when RSC loading
   * @default 'gzip'
   */
  deferParsing?: 'none' | 'json' | 'gzip';
  /** The CodeContent component that renders the code display and syntax highlighting */
  children: React.ReactNode;
  /** Loading placeholder shown while code is being processed */
  fallback?: React.ReactNode;
  /** Skip showing fallback content entirely */
  skipFallback?: boolean;
}

CodeHighlighterProps

Main props for the CodeHighlighter component. Supports both build-time precomputation and runtime code loading with extensive customization options. Generic type T allows for custom props to be passed to Content and ContentLoading components.

type CodeHighlighterProps<T extends {}> = {
  /** Component to show while code is being loaded or processed */
  ContentLoading?: React.ComponentType<ContentLoadingProps<T>>;
  /** Display name for the code example, used for identification and titles */
  name?: string;
  /** URL-friendly identifier for deep linking and navigation */
  slug?: string;
  /** Source URL where the code content originates from */
  url?: string;
  /** Static code content with variants and metadata */
  code?: Code;
  /** React components for live preview alongside code */
  components?: Components;
  /** What type of variants are available (e.g., a type `packageManager` when variants `npm` and `yarn` are available) */
  variantType?: string;
  /** Static variant names that should be fetched at runtime */
  variants?: string[];
  /** Currently selected variant name */
  variant?: string;
  /** Currently selected file name */
  fileName?: string;
  /** Language for syntax highlighting (e.g., 'tsx', 'css'). When provided, fileName is not required for parsing. */
  language?: string;
  /** Default variant to show on first load */
  initialVariant?: string;
  /** Fallback variant when the requested variant is not available */
  defaultVariant?: string;
  /** Global static code snippets to inject, typically for styling or tooling */
  globalsCode?: (string | Code)[];
  /** Pre-computed code data from build-time optimization */
  precompute?: Code;
  /** Whether fallback content should include extra files */
  fallbackUsesExtraFiles?: boolean;
  /** Whether fallback content should include all variants */
  fallbackUsesAllVariants?: boolean;
  /** Enable controlled mode for external code state management */
  controlled?: boolean;
  /** Raw code string for simple use cases */
  children?: string;
  /**
   * When to perform syntax highlighting and code processing
   * @default 'idle'
   */
  highlightAfter?: 'init' | 'stream' | 'hydration' | 'idle';
  /**
   * When to enhance the code display with interactivity
   * @default 'idle'
   */
  enhanceAfter?: 'init' | 'stream' | 'hydration' | 'idle';
  /** Force client-side rendering even when server rendering is available */
  forceClient?: boolean;
  /**
   * Defer parsing and populating the AST into memory until the code is enhanced
   * Applies only in production when RSC loading
   * @default 'gzip'
   */
  deferParsing?: 'none' | 'json' | 'gzip';
  /** Function to load code metadata from a URL */
  loadCodeMeta?: LoadCodeMeta;
  /** Function to load specific variant metadata */
  loadVariantMeta?: LoadVariantMeta;
  /** Function to load raw source code and dependencies */
  loadSource?: LoadSource;
  /** Array of source transformers for code processing (e.g., TypeScript to JavaScript) */
  sourceTransformers?: SourceTransformers;
  /** Promise resolving to a source parser for syntax highlighting */
  sourceParser?: Promise<ParseSource>;
  /** Array of source enhancers that run after parsing to enhance the HAST tree */
  sourceEnhancers?: SourceEnhancers;
  /**
   * Optional URL-prefix rewrite forwarded to .
   * Lets the demo factory translate local `file://` URLs returned by
   * `loadSource` into hosted URLs before they reach the client.
   */
  urlPrefix?: { from: string; to: string };
  /** Component to render the code content and preview */
  Content: React.ComponentType<ContentProps<T>>;
  /** Additional props passed to the Content component */
  contentProps?: T;
}

CodeIdentityProps

Basic identification and metadata props for code examples

type CodeIdentityProps = {
  /** Display name for the code example, used for identification and titles */
  name?: string;
  /** URL-friendly identifier for deep linking and navigation */
  slug?: string;
  /** Source URL where the code content originates from */
  url?: string;
}

CodeLoadingProps

Loading and processing configuration props

type CodeLoadingProps = {
  /** Pre-computed code data from build-time optimization */
  precompute?: Code;
  /** Whether fallback content should include extra files */
  fallbackUsesExtraFiles?: boolean;
  /** Whether fallback content should include all variants */
  fallbackUsesAllVariants?: boolean;
  /** Enable controlled mode for external code state management */
  controlled?: boolean;
  /** Raw code string for simple use cases */
  children?: string;
  /**
   * When to perform syntax highlighting and code processing
   * @default 'idle'
   */
  highlightAfter?: 'init' | 'stream' | 'hydration' | 'idle';
  /**
   * When to enhance the code display with interactivity
   * @default 'idle'
   */
  enhanceAfter?: 'init' | 'stream' | 'hydration' | 'idle';
  /** Force client-side rendering even when server rendering is available */
  forceClient?: boolean;
  /**
   * Defer parsing and populating the AST into memory until the code is enhanced
   * Applies only in production when RSC loading
   * @default 'gzip'
   */
  deferParsing?: 'none' | 'json' | 'gzip';
}

CodeRenderingProps

Component and rendering props

type CodeRenderingProps<T extends {}> = {
  /** Component to render the code content and preview */
  Content: React.ComponentType<ContentProps<T>>;
  /** Additional props passed to the Content component */
  contentProps?: T;
}

CollapseMap

Tracks comments that were collapsed onto a line when their original lines were deleted. Keyed by the line they collapsed onto; each entry records the original offset from the edit line so the collapse can be reversed.

type CollapseMap = { [key: number]: { offset: number; comments: string[] }[] }

Components

type Components = { [key: string]: React.ReactNode }

ContentLoadingProps

type ContentLoadingProps<T extends {}> = ContentLoadingVariant &
  CodeIdentityProps & { extraVariants?: Record<string, ContentLoadingVariant> } & T & {
    component: React.ReactNode;
    components?: Record<string, React.ReactNode>;
    initialFilename?: string;
  }

ContentLoadingVariant

type ContentLoadingVariant = {
  fileNames?: string[];
  source?: React.ReactNode;
  extraSource?: { [fileName: string]: React.ReactNode };
}

ContentProps

type ContentProps<T extends {}> = CodeIdentityProps &
  Pick<CodeContentProps, 'code' | 'components' | 'variantType'> &
  T

ControlledCode

type ControlledCode = { [key: string]: ControlledVariantCode | null | undefined }

ControlledVariantCode

type ControlledVariantCode = {
  /** Name of the file (e.g., 'Button.tsx') */
  fileName?: string;
  /** Language for syntax highlighting (e.g., 'tsx', 'css'). When provided, fileName is not required. */
  language?: string;
  /** Flattened path for the file */
  path?: string;
  url?: string;
  source?: string | null;
  extraFiles?: ControlledVariantExtraFiles;
  filesOrder?: string[];
  comments?: SourceComments;
  collapseMap?: CollapseMap;
  totalLines?: number;
  emptyLines?: number[];
}

ControlledVariantExtraFiles

type ControlledVariantExtraFiles = {
  [fileName: string]: {
    source: string | null;
    comments?: SourceComments;
    collapseMap?: CollapseMap;
    totalLines?: number;
    emptyLines?: number[];
  };
}

ExternalImportItem

type ExternalImportItem = {
  name: string;
  type: 'named' | 'default' | 'namespace';
  isType?: boolean;
}

Externals

type Externals = { [key: string]: ExternalImportItem[] }

HastRoot

type HastRoot = {
  data?: RootData & {
    totalLines?: number;
    collapsible?: boolean;
    frameSize?: number;
    appliedEnhancers?: string[];
  };
}

LoadFallbackCodeOptions

Options for loading fallback code with various configuration flags

type LoadFallbackCodeOptions = {
  /** Flag to indicate if syntax highlighting should be performed */
  shouldHighlight?: boolean;
  /** Specific filename to initially display */
  initialFilename?: string;
  /** Array of global code to include (overrides LoadFileOptions.globalsCode with different type) */
  globalsCode?: (string | Code)[];
  /** Disable applying source transformers */
  disableTransforms?: boolean;
  /** Disable parsing source strings to AST */
  disableParsing?: boolean;
  /** Maximum recursion depth for loading nested extra files */
  maxDepth?: number;
  /** Set of already loaded file URLs to prevent circular dependencies */
  loadedFiles?: Set<string>;
  /**
   * Output format for the loaded file
   * @default 'hast'
   */
  output?: 'hast' | 'hastJson' | 'hastCompressed';
  /**
   * Optional URL-prefix rewrite applied to the loaded variant's `url` and any
   * string-form `extraFiles` entries. Useful for translating local `file://`
   * URLs (e.g. those returned by `loadServerCodeSource`) into hosted URLs (e.g.
   * `https://github.com/owner/repo/tree/<branch>/`) before they reach the
   * client.
   */
  urlPrefix?: { from: string; to: string };
  /** Function to load code metadata from a URL */
  loadCodeMeta?: LoadCodeMeta;
  /** Function to load specific variant metadata */
  loadVariantMeta?: LoadVariantMeta;
  /** Function to load raw source code and dependencies */
  loadSource?: LoadSource;
  /** Array of source transformers for code processing (e.g., TypeScript to JavaScript) */
  sourceTransformers?: SourceTransformers;
  /** Promise resolving to a source parser for syntax highlighting */
  sourceParser?: Promise<ParseSource>;
  /** Array of source enhancers that run after parsing to enhance the HAST tree */
  sourceEnhancers?: SourceEnhancers;
  /** Static variant names that should be fetched at runtime */
  variants?: string[];
  /** Whether fallback content should include extra files */
  fallbackUsesExtraFiles?: boolean;
  /** Whether fallback content should include all variants */
  fallbackUsesAllVariants?: boolean;
}

LoadFileOptions

Options for controlling file loading behavior

type LoadFileOptions = {
  /** Disable applying source transformers */
  disableTransforms?: boolean;
  /** Disable parsing source strings to AST */
  disableParsing?: boolean;
  /** Maximum recursion depth for loading nested extra files */
  maxDepth?: number;
  /** Set of already loaded file URLs to prevent circular dependencies */
  loadedFiles?: Set<string>;
  /** Side effects code to inject into extraFiles */
  globalsCode?: (string | VariantCode)[];
  /**
   * Output format for the loaded file
   * @default 'hast'
   */
  output?: 'hast' | 'hastJson' | 'hastCompressed';
  /**
   * Optional URL-prefix rewrite applied to the loaded variant's `url` and any
   * string-form `extraFiles` entries. Useful for translating local `file://`
   * URLs (e.g. those returned by `loadServerCodeSource`) into hosted URLs (e.g.
   * `https://github.com/owner/repo/tree/<branch>/`) before they reach the
   * client.
   */
  urlPrefix?: { from: string; to: string };
}

LoadVariantOptions

Options for the loadIsomorphicCodeVariant function, extending LoadFileOptions with required function dependencies

type LoadVariantOptions = {
  /** Disable applying source transformers */
  disableTransforms?: boolean;
  /** Disable parsing source strings to AST */
  disableParsing?: boolean;
  /** Maximum recursion depth for loading nested extra files */
  maxDepth?: number;
  /** Set of already loaded file URLs to prevent circular dependencies */
  loadedFiles?: Set<string>;
  /** Side effects code to inject into extraFiles */
  globalsCode?: (string | VariantCode)[];
  /**
   * Output format for the loaded file
   * @default 'hast'
   */
  output?: 'hast' | 'hastJson' | 'hastCompressed';
  /**
   * Optional URL-prefix rewrite applied to the loaded variant's `url` and any
   * string-form `extraFiles` entries. Useful for translating local `file://`
   * URLs (e.g. those returned by `loadServerCodeSource`) into hosted URLs (e.g.
   * `https://github.com/owner/repo/tree/<branch>/`) before they reach the
   * client.
   */
  urlPrefix?: { from: string; to: string };
  /** Promise resolving to a source parser for syntax highlighting */
  sourceParser?: Promise<ParseSource>;
  /** Function to load raw source code and dependencies */
  loadSource?: LoadSource;
  /** Function to load specific variant metadata */
  loadVariantMeta?: LoadVariantMeta;
  /** Array of source transformers for code processing (e.g., TypeScript to JavaScript) */
  sourceTransformers?: SourceTransformers;
  /** Array of source enhancers that run after parsing to enhance the HAST tree */
  sourceEnhancers?: SourceEnhancers;
}

SourceComments

Comments extracted from source code, keyed by line number. Each line number maps to an array of comment strings found on that line.

type SourceComments = { [key: number]: string[] }

SourceEnhancers

Array of source enhancer functions that run in order after parsing.

type SourceEnhancers = SourceEnhancer[]

SourceTransformer

type SourceTransformer = { extensions: string[]; transformer: TransformSource }

SourceTransformers

type SourceTransformers = SourceTransformer[]

Transforms

type Transforms = { [key: string]: { delta: Delta; fileName?: string } }

VariantCode

Complete code variant definition with source, metadata, and configuration. Extends CodeMeta with all the information needed to display and process a code example.

type VariantCode = {
  /** Name of the file (e.g., 'Button.tsx') */
  fileName?: string;
  /** Language for syntax highlighting (e.g., 'tsx', 'css'). When provided, fileName is not required. */
  language?: string;
  /** Flattened path for the file */
  path?: string;
  /** Source URL where this variant originates */
  url?: string;
  /** Main source content for this variant */
  source?: VariantSource;
  /** Additional files associated with this variant */
  extraFiles?: VariantExtraFiles;
  /** Prefix for metadata keys, e.g. /src */
  metadataPrefix?: string;
  /** External module dependencies */
  externals?: string[];
  /** The name of the export for this variant's entrypoint */
  namedExport?: string;
  /** Order in which files should be displayed */
  filesOrder?: string[];
  /** Transformations that can be applied to the source */
  transforms?: Transforms;
  /** Whether all files in the variant are explicitly listed */
  allFilesListed?: boolean;
  /** Skip generating source transformers for this variant */
  skipTransforms?: boolean;
  /** Comments extracted from source, stored when parsing is disabled for later use */
  comments?: SourceComments;
}

VariantExtraFiles

Additional files associated with a code variant. Can be either simple string content or objects with source and transformation options.

type VariantExtraFiles = {
  [fileName: string]:
    | string
    | {
        source?: VariantSource;
        language?: string;
        transforms?: Transforms;
        skipTransforms?: boolean;
        metadata?: boolean;
        path?: string;
        relativeUrl?: string;
        comments?: SourceComments;
      };
}

VariantSource

type VariantSource = string | HastRoot | { hastJson: string } | { hastCompressed: string }