> For AI agents: the complete documentation index is available at https://rspress.rs/llms.txt, the full documentation bundle is available at https://rspress.rs/llms-full.txt.

# CodeBlockRuntime

`CodeBlockRuntime` renders runnable [code blocks](https://rspress.rs/guide/use-mdx/code-blocks.md) at runtime.

## Usage

```tsx title="index.mdx"
import { CodeBlockRuntime } from '@rspress/core/theme';

export default function Page() {
  return (
    <CodeBlockRuntime
      lang="js"
      title="index.js"
      code={`console.log('Hello World!')`}
      shikiOptions={{}}
    />
  );
}
```


```js title=index.js
console.log('Hello World!')
```

Pass `lang`, `title`, and `code` to render the block; `shikiOptions` customizes highlighting and also supports transformers.

:::warning

Use `CodeBlockRuntime` only when necessary. It increases runtime bundle size, especially when multiple languages are included, and cannot benefit from compile-time highlighting.

:::

## Using shiki options

Here is an example using a transformer for line highlighting:

```mdx title="foo.mdx"
import { CodeBlockRuntime } from '@rspress/core/theme';
import { transformerNotationHighlight } from '@shikijs/transformers';

<CodeBlockRuntime
  lang="ts"
  title="highlight.ts"
  code={`console.log('Highlighted'); // [\!code highlight]
// [\!code highlight:1]
console.log('Highlighted');
console.log('Not highlighted');`}
  shikiOptions={{
    transformers: [transformerNotationHighlight()],
  }}
/>
```


```ts title=highlight.ts
console.log('Highlighted'); // [!code highlight]
// [!code highlight:1]
console.log('Highlighted');
console.log('Not highlighted');
```

## Importing file content

You can use the `?raw` query to import file content as a string and pass it to the `code` prop. See [Rsbuild - Static Assets](https://rsbuild.rs/guide/basic/static-assets) for details.

```mdx title="foo.mdx"
import { CodeBlockRuntime } from '@rspress/core/theme';
import codeContent from './example.ts?raw';

<CodeBlockRuntime lang="ts" title="example.ts" code={codeContent} />
```

This approach is suitable for scenarios where you need to dynamically display external file content, such as showing example code files.

:::warning

If you only need to reference external files as code blocks, use the static [file code block](https://rspress.rs/guide/use-mdx/code-blocks.md#file-code-block) syntax. It is processed at compile time, with better performance and a smaller bundle size.

:::