---
# WARNING: Do not edit this file directly, your changes will be overwritten!
# This file is auto-generated from a template inside "scripts/typedoc/templates".
title: Plugin API
---

import PropertySignature from '@components/PropertySignature.astro'

## ExpressiveCodePlugin

An interface that defines an Expressive Code plugin. To add a custom plugin, you pass an object matching this interface into the `plugins` array property of the engine configuration.

### Properties

#### name

<PropertySignature>
- Type: `string`
</PropertySignature>

The display name of the plugin. This is the only required property. It is used by the engine to display messages concerning the plugin, e.g. when it encounters an error.

#### baseStyles?

<PropertySignature>
- Type: `string` \| [`BaseStylesResolverFn`](/reference/plugin-api/#basestylesresolverfn)
</PropertySignature>

The CSS styles that should be added to every page containing code blocks.

All styles are scoped to Expressive Code by default, so they will not affect the rest of the page. SASS-like nesting is supported. If you want to add global styles, you can use the `@at-root` rule or target `:root`, `html` or `body` in your selectors.

The engine's `getBaseStyles` function goes through all registered plugins and collects their base styles.

If you provide a function instead of a string, it is called with an object argument of type [ResolverContext](/reference/plugin-api/#resolvercontext), and is expected to return a string or a string promise.

The calling code must take care of actually adding the collected styles to the page. For example, it could create a site-wide CSS stylesheet from the base styles and insert a link to it, or it could insert the base styles into a `<style>` element.

#### hooks?

<PropertySignature>
- Type: [`ExpressiveCodePluginHooks`](/reference/plugin-hooks/)
</PropertySignature>

A set of functions that should be called by the engine at specific points in the rendering process. See [ExpressiveCodePluginHooks](/reference/plugin-hooks/) for a list of available hooks.

#### jsModules?

<PropertySignature>
- Type: `string`[] \| [`JsModulesResolverFn`](/reference/plugin-api/#jsmodulesresolverfn)
</PropertySignature>

JavaScript modules (pure code without any wrapping `script` tags) that should be added to every page containing code blocks.

The engine's `getJsModules` function goes through all registered plugins, collects their JS modules and deduplicates them.

If you provide a function instead of a string, it is called with an object argument of type [ResolverContext](/reference/plugin-api/#resolvercontext), and is expected to return a string or a string promise.

The calling code must take care of actually adding the collected scripts to the page. For example, it could create site-wide JavaScript files from the returned modules and refer to them in a script tag with `type="module"`, or it could insert them into inline `<script type="module">` elements.

#### styleSettings?

<PropertySignature>
- Type: [`PluginStyleSettings`](/reference/plugin-api/#pluginstylesettings)
</PropertySignature>

An instance of `PluginStyleSettings` that is used to define the plugin's CSS variables.

## PluginStyleSettings

Represents a strongly typed set of style settings provided by a plugin (or core).

The constructor expects an object with a `defaultSettings` property. This property must contain the default values for all settings and will be made available as a public instance property. Allowed default value types are plain values (e.g. strings), an array of two values to provide a dark and light variant, or resolver functions that return one of these types.

If you are writing a plugin that provides style overrides, please merge your style overrides into the `StyleSettings` interface declaration provided by the `@expressive-code/core` module. You can see an example of this below.

As a plugin author, you should also assign an instance of this class to your plugin's
`styleSettings` property. This allows the engine to automatically declare CSS variables for your style settings in all theme variants defined in the config.

To consume the CSS variables in your plugin's `baseStyles` or anywhere else, see the
cssVar method to get a CSS variable reference to any style setting.

If CSS variables should not be generated for some of your style settings, you can exclude them using the `cssVarExclusions` property of the object passed to the constructor.

If you want to provide descriptive names for your style settings, but keep the generated CSS variable names short, you can pass an array of search and replace string pairs to the
`cssVarReplacements` property of the object passed to the constructor. The replacements will be applied to all generated CSS variable names.

If you want to prevent unitless values for specific style settings (e.g. because you intend to use them in CSS calculations), you can pass an array of style setting paths to the
`preventUnitlessValues` property of the object passed to the constructor. If the user passes a unitless value to one of these settings, the engine will automatically add `px` to the value.

### Example

```ts
// When using TypeScript: Declare the types of your style settings
interface FramesStyleSettings {
  fontFamily: string
  fontSize: string
  minContrast: string
  titleBarForeground: string
}

// When using TypeScript: Merge your style settings into the core module's `StyleSettings`
declare module '@expressive-code/core' {
  export interface StyleSettings {
    frames: FramesStyleSettings
  }
}

const framesStyleSettings = new PluginStyleSettings({
  defaultValues: {
    frames: {
      fontFamily: 'sans-serif',
      fontSize: '1rem',
      minContrast: '5',
      titleBarForeground: ({ theme }) => theme.colors['editor.foreground'],
    }
  },
  cssVarExclusions: ['frames.minContrast'],
})

// ↓↓↓

framesStyleSettings.defaultValues.frames.fontFamily         // 'sans-serif'
framesStyleSettings.defaultValues.frames.fontSize           // '1rem'
framesStyleSettings.defaultValues.frames.minContrast        // '5'
framesStyleSettings.defaultValues.frames.titleBarForeground // ({ theme }) => theme.colors['editor.foreground']
```

### Constructors

#### new PluginStyleSettings(options)

- <code class="function-signature">**new PluginStyleSettings**(options): [PluginStyleSettings](/reference/plugin-api/#pluginstylesettings)</code>

##### Arguments

| Parameter | Type |
| :------ | :------ |
| `options` | `Object` |
| `options.defaultValues` | `Partial`\<[`UnresolvedStyleSettings`](/reference/plugin-api/#unresolvedstylesettings)\> |
| `options.cssVarExclusions`? | [`StyleSettingPath`](/reference/plugin-api/#stylesettingpath)[] |
| `options.cssVarReplacements`? | \[`string`, `string`\][] |
| `options.preventUnitlessValues`? | [`StyleSettingPath`](/reference/plugin-api/#stylesettingpath)[] |

### Properties

#### cssVarExclusions

<PropertySignature>
- Type: **readonly** [`StyleSettingPath`](/reference/plugin-api/#stylesettingpath)[]
</PropertySignature>

#### cssVarReplacements

<PropertySignature>
- Type: **readonly** \[`string`, `string`\][]
</PropertySignature>

#### defaultValues

<PropertySignature>
- Type: **readonly** `Partial`\<[`UnresolvedStyleSettings`](/reference/plugin-api/#unresolvedstylesettings)\>
</PropertySignature>

#### preventUnitlessValues

<PropertySignature>
- Type: **readonly** [`StyleSettingPath`](/reference/plugin-api/#stylesettingpath)[]
</PropertySignature>

## AttachedPluginData

A class that allows plugins to attach custom data to objects like code blocks, and to optionally allow external access to this data in a type-safe manner.

### Usage example

```ts
// pluginDataExample.ts
import { AttachedPluginData, ExpressiveCodePlugin } from '@expressive-code/core'

export function pluginDataExample(): ExpressiveCodePlugin {
  return {
    name: 'AttachedPluginDataExample',
    hooks: {
      preprocessMetadata: ({ codeBlock }) => {
        // Get a reference to the block's data object
        const blockData = pluginFramesData.getOrCreateFor(codeBlock)

        // Example: Store the meta string in the data object
        // and remove it from the block
        blockData.extractedMeta = codeBlock.meta
        codeBlock.meta = ''
      },
      postprocessRenderedBlock: ({ codeBlock }) => {
        // Try to retrieve the stored title from the block's data object
        const blockData = pluginFramesData.getOrCreateFor(codeBlock)

        // Log the extracted data
        console.dir(blockData)
      },
    },
  }
}

// Define the data object type
export interface PluginFramesData {
  extractedMeta?: string
}

// Create a singleton instance that allows attaching this type of data
// to any object and to retrieve it later.
// Note: Exporting is optional. This can be useful if multiple plugins
//       need to work together.
export const pluginFramesData = new AttachedPluginData<PluginFramesData>(
  // This function initializes the attached data
  // in case nothing was attached to an object yet
  () => ({})
)
```

### Type parameters

| Parameter |
| :------ |
| `PluginDataType` |

### Constructors

#### new AttachedPluginData(getInitialValueFn)

- <code class="function-signature">**new AttachedPluginData**\<PluginDataType\>(getInitialValueFn): [AttachedPluginData](/reference/plugin-api/#attachedplugindata)\<PluginDataType\></code>

##### Arguments

| Parameter | Type |
| :------ | :------ |
| `getInitialValueFn` | () => `PluginDataType` |

### Methods

#### getOrCreateFor()

- <code class="function-signature">**getOrCreateFor**(target): PluginDataType</code>

##### Arguments

| Parameter | Type |
| :------ | :------ |
| `target` | `PluginDataTarget` |

#### setFor()

- <code class="function-signature">**setFor**(target, data): void</code>

##### Arguments

| Parameter | Type |
| :------ | :------ |
| `target` | `PluginDataTarget` |
| `data` | `PluginDataType` |

## Referenced types

### BaseStylesResolverFn

<PropertySignature>
- Type: (`context`) => `string` \| `Promise`\<`string`\>
</PropertySignature>

A function that you can assign to the [`baseStyles`](#basestyles) property of an [`ExpressiveCodePlugin`](#expressivecodeplugin).

The engine will call it when going through all registered plugins and collecting their base styles.

:::tip
You can use this to include CSS variables generated from any style settings, including your own [`PluginStyleSettings`](#pluginstylesettings), into your plugin's base styles.

The function will be called with a `context` argument of type [`ResolverContext`](#resolvercontext) that provides helpful functions like `cssVar` to access any generated CSS variable by its style setting path.
:::

#### Arguments

| Parameter | Type |
| :------ | :------ |
| `context` | [`ResolverContext`](/reference/plugin-api/#resolvercontext) |

### JsModulesResolverFn

<PropertySignature>
- Type: (`context`) => `string`[] \| `Promise`\<`string`[]\>
</PropertySignature>

A function that you can assign to the [`jsModules`](#jsmodules) property of an [`ExpressiveCodePlugin`](#expressivecodeplugin).

The engine will call it when going through all registered plugins and collecting their JS modules.

#### Arguments

| Parameter | Type |
| :------ | :------ |
| `context` | [`ResolverContext`](/reference/plugin-api/#resolvercontext) |

### ResolverContext

<PropertySignature>
- Type: `Object`
</PropertySignature>

A context object that the engine passes to most hook functions.

It provides access to theme-dependent CSS variables, all resolved style variants based on the configured themes and settings, and the config-dependent wrapper class name.

#### Object properties

<dl class="type-declaration-list">
<dt>cssVar</dt>
<dd>
<PropertySignature>
- Type: (`styleSetting`, `fallbackValue`?) => `string`
</PropertySignature>
</dd>
<dt>cssVarName</dt>
<dd>
<PropertySignature>
- Type: (`styleSetting`) => `string`
</PropertySignature>
</dd>
<dt>styleVariants</dt>
<dd>
<PropertySignature>
- Type: [`StyleVariant`](/reference/plugin-api/#stylevariant)[]
</PropertySignature>
</dd>
</dl>

### ResolvedStyleSettingsByPath

<PropertySignature>
- Type: `Map`\<[`StyleSettingPath`](/reference/plugin-api/#stylesettingpath), `string`\>
</PropertySignature>

### StyleResolverFn

<PropertySignature>
- Type: (`context`) => [`StyleValueOrValues`](/reference/plugin-api/#stylevalueorvalues)
</PropertySignature>

A function that resolves a single style setting to a [StyleValueOrValues](/reference/plugin-api/#stylevalueorvalues).

You can assign this to any style setting to dynamically generate style values based on the current theme.

This function is called once for each style variant in the engine's `styleVariants` array, which includes one entry per theme in the engine's `themes` configuration option.

#### Arguments

| Parameter | Type | Description |
| :------ | :------ | :------ |
| `context` | `Object` | - |
| `context.resolveSetting` | (`settingPath`) => `string` | - |
| `context.styleVariantIndex` | `number` | The index in the engine's `styleVariants` array that's currently being resolved. |
| `context.theme` | [`ExpressiveCodeTheme`](/reference/core-api/#expressivecodetheme) | - |

### StyleSettingPath

<PropertySignature>
- Type: `FlattenKeys`\<`StyleSettings`\>
</PropertySignature>

### StyleValueOrValues

<PropertySignature>
- Type: `string` \| \[`string`, `string`\]
</PropertySignature>

The value of a single style setting. You can either set it to a string, or an array of two strings.

If you use the array form, the first value will be used for dark themes, and the second value for light themes.

### StyleVariant

<PropertySignature>
- Type: `Object`
</PropertySignature>

#### Object properties

<dl class="type-declaration-list">
<dt>cssVarDeclarations</dt>
<dd>
<PropertySignature>
- Type: `Map`\<`string`, `string`\>
</PropertySignature>
</dd>
<dt>resolvedStyleSettings</dt>
<dd>
<PropertySignature>
- Type: [`ResolvedStyleSettingsByPath`](/reference/plugin-api/#resolvedstylesettingsbypath)
</PropertySignature>
</dd>
<dt>theme</dt>
<dd>
<PropertySignature>
- Type: [`ExpressiveCodeTheme`](/reference/core-api/#expressivecodetheme)
</PropertySignature>
</dd>
</dl>

### UnresolvedPluginStyleSettings

<PropertySignature>
- Type: `{ [SettingName in keyof T]: UnresolvedStyleValue }`
</PropertySignature>

#### Type parameters

| Parameter |
| :------ |
| `T` |

### UnresolvedStyleValue

<PropertySignature>
- Type: [`StyleValueOrValues`](/reference/plugin-api/#stylevalueorvalues) \| [`StyleResolverFn`](/reference/plugin-api/#styleresolverfn)
</PropertySignature>

This is the value type for all style overrides. It allows either static style values or a resolver function.

### UnresolvedStyleSettings

<PropertySignature>
- Type: `{ [K in keyof StyleSettings]: StyleSettings[K] extends object ? UnresolvedPluginStyleSettings<StyleSettings[K]> : UnresolvedStyleValue }`
</PropertySignature>
