Code Provider

The CodeProvider component provides client-side functions for fetching source code and highlighting it. It's designed for cases where you need to render code blocks or demos based on client-side state or dynamic content loading. It also provides heavy processing functions that are moved from individual components to the context for better performance and code splitting.

CodeProvider implements the Props Context Layering pattern by providing heavy functions via context that can't be serialized across the server-client boundary.

• Client-side syntax highlighting with support for multiple languages using Starry Night
• Dynamic code fetching from external sources or APIs
• Context-based API for sharing highlighting functions across components
• Custom loading functions for different code sources
• Browser-only execution with SSR safety
• Heavy function provision for code processing (parsing, transforming, loading)

Use CodeProvider when you need:

• Dynamic code loading from external sources or APIs
• Client-side code highlighting without build-time optimization
• Custom code fetching logic for different data sources
• Shared highlighting context across multiple components

Note

If you need interactive code editing with shared state management, use the CodeControllerContext instead.

The simplest way to use CodeProvider is to wrap components that need client-side highlighting:

Base Code Provider

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

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

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

Fetch Demo Code Provider

For more dynamic use cases, you can provide custom loading functions that fetch code from external sources:

import * as React from 'react';
import { CodeProviderGitHub } from './CodeProviderGitHub';
import { DemoCheckboxBasic } from './demo-basic';

export function Docs() {
  return (
    <CodeProviderGitHub>
      <DemoCheckboxBasic />
    </CodeProviderGitHub>
  );
}

Recursive Fetch Demo Code Provider

The previous demo asks loadVariantMeta to enumerate every file a variant exposes up front. The recursive variant flips that around: loadCodeMeta only resolves the variant entry points, and loadSource parses each file with parseImportsAndComments and reports the relative imports as extraFiles. The framework then calls loadSource for each newly discovered file, so the import graph is walked one node at a time.

import * as React from 'react';
import { CodeProviderGitHub } from './CodeProviderGitHub';
import { DemoCheckboxBasic } from './demo-basic';

export function Docs() {
  return (
    <CodeProviderGitHub>
      <DemoCheckboxBasic />
    </CodeProviderGitHub>
  );
}

In practice the eager variant is the right starting point for documentation that mirrors a small, hand-curated set of files. Reach for the recursive variant once a demo grows beyond a couple of files or starts importing helpers from sibling directories — at that point the savings from on-demand resolution and SHA-pinned caching outweigh the extra request round-trips.

CodeProvider works seamlessly with CodeHighlighter for dynamic content:

import { CodeProvider } from '@mui/internal-docs-infra/CodeProvider';
import { CodeHighlighter } from '@mui/internal-docs-infra/CodeHighlighter';
import { CodeContent } from './CodeContent';

function DynamicCodeExample() {
  return (
    <CodeProvider>
      <CodeHighlighter Content={CodeContent}>{`console.log("Dynamic code!");`}</CodeHighlighter>
    </CodeProvider>
  );
}

You can provide custom functions for loading code from different sources:

import { CodeProvider } from '@mui/internal-docs-infra/CodeProvider';
import type { LoadCodeMeta, LoadSource } from '@mui/internal-docs-infra/CodeHighlighter';

const loadCodeFromApi: LoadCodeMeta = async (url: string) => {
  const response = await fetch(`/api/code/${encodeURIComponent(url)}`);
  return response.json();
};

const loadSourceFromGitHub: LoadSource = async (url: string) => {
  const response = await fetch(url.replace('file://', 'https://raw.githubusercontent.com/'));
  const source = await response.text();
  return { source };
};

function MyApp() {
  return (
    <CodeProvider loadCodeMeta={loadCodeFromApi} loadSource={loadSourceFromGitHub}>
      {/* Your components */}
    </CodeProvider>
  );
}

LoadCodeMeta | undefined

LoadSource | undefined

LoadVariantMeta | undefined

SourceEnhancer[] | undefined

React.ReactNode

When the runtime is a browser that supports Web Workers, CodeProvider automatically spawns a single dedicated worker per provider and uses it to syntax-highlight source code while the user is typing in an editable code block. This keeps the main thread responsive during fast keystrokes — the synchronous highlighter that runs after each commit can still take low single-digit milliseconds for large files, which is enough to drop a frame on slower devices.

1. The provider creates the worker on its first browser-only effect.
2. The worker module and the (lazy) grammar chunk are both fetched via dynamic import(...), so neither ships in SSR bundles and neither blocks first paint.
3. Grammars are sent across the boundary exactly once via postMessage. The worker calls createStarryNight(grammars) and acknowledges with init-ack. If grammar creation throws, the worker posts init-error and every queued parse request rejects.
4. While initialization is in flight, parse requests are queued and drained in arrival order on init-ack.
5. On unmount the worker is terminated; any still-pending requests reject with Worker terminated.

Each parse request accepts an optional AbortSignal. When a newer keystroke supersedes an older one, the consumer (typically useEditable's preParse hook) aborts the older signal so the worker's response is dropped on arrival rather than replacing fresher highlighted output. Pre-aborted signals reject synchronously without any cross-thread traffic.

The worker integration is fully automatic — no opt-in is required. A consumer that wraps an editable code block in CodeProvider will see worker-backed highlighting as long as Worker is defined and the editable's host (typically useCode) provides a setSource callback. When either condition is missing the editable falls back to the synchronous main-thread highlighter and the UX is unchanged.

Note

The same grammar chunk powers both the main-thread parseSource and the worker-thread parser, so enabling the worker does not double the grammar download cost.

1. Wrap at the appropriate level - Place CodeProvider high enough to cover all components that need highlighting
2. Handle loading states - Remember that highlighting is async, so provide loading feedback
3. Use for dynamic content - CodeProvider is perfect for code that can't be precomputed
4. Consider performance - For static content, precomputed demos are faster
5. Handle errors gracefully - Custom loading functions should include proper error handling

Highlighting not working:

• Ensure components are wrapped in CodeProvider
• Check browser console for loading errors
• Verify that code is being processed client-side

Performance issues:

• Consider using precomputed demos for static content
• Implement loading states for better UX
• Cache loaded code when possible

SSR errors:

• CodeProvider automatically handles SSR safety
• Use forceClient on CodeHighlighter when needed
• Ensure custom loading functions handle server/client differences