---
title: Code Component
---

import { Code } from '@astrojs/starlight/components'
import ConfigVariants from '@components/ConfigVariants.astro'
import IntegrationVariants from '@components/IntegrationVariants.astro'
import PropertySignature from '@components/PropertySignature.astro'

In addition to rendering fenced code blocks in markdown & MDX documents, the Expressive Code Astro & Starlight integrations also provide a `<Code>` component that can be used in `.mdx` and `.astro` files.

In contrast to static fenced code blocks, the `<Code>` component allows you to dynamically define a code block's contents using props. This makes it possible to render code blocks from variables or data coming from external sources like files, databases or APIs.

## Basic usage

To use the `<Code>` component, you must first import it into your file. The location and syntax of the import statement depend on the file type and integration you're using:

### Usage in `.mdx` files

To get started, add an import statement to the content section of your `.mdx` file (the part below the frontmatter block). You can then use the component anywhere in the content.

<IntegrationVariants lang="mdx" title="src/content/docs/example.mdx" ins={[4, 6]} code={`
---
title: My example page
---
import { Code } from 'astro-expressive-code/components'

<Code code="console.log('Hello world!')" lang="js" />
`} />

The code above generates the following on the page:

<Code code="console.log('Hello world!')" lang="js" />

### Usage in `.astro` files

The `<Code>` component enables you to render code blocks in `.astro` files. This allows you to use all features of Expressive Code in your pages, and even creating custom components that wrap the `<Code>` component to provide additional functionality.

Using the component in `.astro` files works just like in `.mdx` files, except that you need to place the import statement inside the frontmatter block:

```astro title="src/pages/index.astro" ins={3, 8}
---
import MainLayout from '../layouts/MainLayout.astro'
import { Code } from 'astro-expressive-code/components'
---
<MainLayout>
  <h1>My example page</h1>
  <p>Here is some interesting code:</p>
  <Code code="console.log('Hello world!')" lang="js" />
</MainLayout>
```

## Using props to define code blocks

The true power of the `<Code>` component lies in its ability to render code blocks from variables or data coming from external sources like files, databases or APIs.

To do this, set the component's props like `code`, `lang`, `title` etc. to variables instead of static values.

<IntegrationVariants lang="mdx" title="src/content/docs/example.mdx" ins={[4, 10]} code={`
---
title: My example page
---
import { Code } from 'astro-expressive-code/components'

export const exampleCode = \`console.log('This could come from a file or CMS!');\`
export const fileName = 'example.js'
export const highlights = ['file', 'CMS']

<Code code={exampleCode} lang="js" title={fileName} mark={highlights} />
`} />

The code above generates the following on the page:

export const exampleCode = `console.log('This could come from a file or CMS!');`;
export const fileName = 'example.js';
export const highlights = ['file', 'CMS'];

<Code code={exampleCode} lang="js" title={fileName} mark={highlights} />

## Importing code from files

Use [Vite's `?raw` import suffix](https://vitejs.dev/guide/assets#importing-asset-as-string) to import any code file as a string. You can then pass this imported string to the `<Code>` component to include it on your page.

This is especially useful when documenting a project, as your code examples will always be up-to-date with the actual code.

You can also use this feature to create reusable snippets and include them in multiple code blocks on your site.

<IntegrationVariants lang="mdx" title="src/content/docs/example.mdx" mark="?raw" code={`
import { Code } from 'astro-expressive-code/components';
import importedCode from '/src/env.d.ts?raw';

<Code code={importedCode} lang="ts" title="src/env.d.ts" />
`} />

The code above generates the following on the page:

import importedCode from '/src/env.d.ts?raw';

<Code code={importedCode} lang="ts" title="src/env.d.ts" />


## Using an `ec.config.mjs` file

The `<Code>` component is designed to automatically pick up the Expressive Code configuration options from your project's Astro config file without requiring any additional setup.

Due to the way Astro works, the Expressive Code integration can only share its configuration with the component by serializing it to JSON. In some situations, this is not possible, e.g. when your configuration includes custom plugins or functions that are not serializable to JSON.

In these cases, you will receive the following error message when trying to use the `<Code>` component:

> *[ERROR] Failed to render a `<Code>` component on page [...]:*
>
> *Your Astro config file contains Expressive Code options that are not serializable to JSON. To use the `<Code>` component, please create a separate config file called `ec.config.mjs` in your project root, move your Expressive Code options object into the config file, and export it as the default export.*

As instructed by the error message, you can fix this issue by creating a separate `ec.config.mjs` file in your project root and moving your Expressive Code options object into the config file. Here is an example of how this file could look like if you're using the [collapsible sections plugin](/plugins/collapsible-sections/):

<ConfigVariants onlyEcConfigFile ins={[]}
  imports={`
    import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections'
  `}
  settings={`
    // Example: Using a custom plugin (which makes this \`ec.config.mjs\` file necessary)
    plugins: [pluginCollapsibleSections()],
    // ... any other options you want to configure
  `}
/>

## Available props

You can find a list of all default props that can be used with the `<Code>` component below.

:::note
Optional plugins can contribute additional props to the `<Code>` component. Please refer to the documentation of the respective plugin for more information.
:::

### code

<PropertySignature>
- Type: string
</PropertySignature>

The plaintext contents of the code block. This property is required and must be set to a non-empty string.

### lang

<PropertySignature>
- Type: string | undefined
- Default: undefined
</PropertySignature>

The code block's language.

Please use a valid [language identifier](/key-features/syntax-highlighting/#supported-languages) to ensure proper syntax highlighting.

### meta

<PropertySignature>
- Type: string | undefined
- Default: undefined
</PropertySignature>

An optional meta string. In markdown or MDX documents, this is the part of the code block's opening fence that comes after the language name.

### locale

<PropertySignature>
- Type: string | undefined
- Default: undefined
</PropertySignature>

The code block's locale (e.g. `en-US` or `de-DE`). This is used by plugins to display localized strings depending on the language of the containing page.

If no locale is defined here, most Expressive Code integrations will attempt to auto-detect the block locale using the configured [`getBlockLocale`](/reference/configuration/#getblocklocale) function, and finally fall back to the configured [`defaultLocale`](/reference/configuration/#defaultlocale).

### title

<PropertySignature>
- Type: string | undefined
- Default: undefined
</PropertySignature>

The code block's title.

Depending on the frame type (code or terminal), this title is displayed by the [frames plugin](/key-features/frames/) either as an open file tab label or as a terminal window title.

### frame

<PropertySignature>
- Type: `'auto' | 'code' | 'terminal' | 'none' | undefined`
- Default: `'auto'`
</PropertySignature>

The code block's [frame type](https://expressive-code.com/key-features/frames/#overriding-frame-types).

### mark / ins / del

<PropertySignature>
- Type: [`MarkerDefinition`](/key-features/text-markers/#markerdefinition) \| [`MarkerDefinition`](/key-features/text-markers/#markerdefinition)[]
- Default: undefined
</PropertySignature>

Defines the code block's [text & line markers](/key-features/text-markers/).

You can either pass a single marker definition or an array of them.

### class

<PropertySignature>
- Type: string | undefined
- Default: undefined
</PropertySignature>

The CSS class name(s) to apply to the code block's container element.

### wrap

<PropertySignature>
- Type: `boolean`
- Default: ``false``
</PropertySignature>

If `true`, word wrapping will be enabled for the code block, causing lines that exceed the available width to wrap to the next line. You can use the `preserveIndent` option to control how wrapped lines are indented.

If `false`, lines that exceed the available width will cause a horizontal scrollbar to appear.

### preserveIndent

<PropertySignature>
- Type: `boolean`
- Default: ``true``
</PropertySignature>

If `true`, wrapped parts of long lines will be aligned with their line's indentation level, making the wrapped code appear to start at the same column. This increases readability of the wrapped code and can be especially useful for languages where indentation is significant, e.g. Python.

If `false`, wrapped parts of long lines will always start at column 1. This can be useful to reproduce terminal output.

:::note
This option only has an effect if `wrap` is `true`. It only affects how the code block is displayed and does not change the actual code. When copied to the clipboard, the code will still contain the original unwrapped lines.
:::

### hangingIndent

<PropertySignature>
- Type: `number`
- Default: ``0``
</PropertySignature>

Defines the number of columns by which all wrapped lines are indented.

This option only has an effect if `wrap` is `true`.

If `preserveIndent` is `true`, this value is added to the indentation of the original line. If `preserveIndent` is `false`, this value is used as the indentation for all wrapped lines.

:::note
This option only affects how the code block is displayed and does not change the actual code. When copied to the clipboard, the code will still contain the original unwrapped lines.
:::
