---
# 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: Core API
---

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

## Engine

### ExpressiveCodeEngine

The Expressive Code engine is responsible for rendering code blocks to a [Hypertext Abstract Syntax Tree (HAST)](https://github.com/syntax-tree/hast) that can be serialized to HTML, as well as generating the required CSS styles and JS modules.

It also provides read-only access to all resolved configuration options through its public properties.

#### Constructors

##### new ExpressiveCodeEngine(config)

- <code class="function-signature">**new ExpressiveCodeEngine**(config): [ExpressiveCodeEngine](/reference/core-api/#expressivecodeengine)</code>

Creates a new instance of the Expressive Code engine.

To minimize overhead caused by loading plugins, you can create a single instance for your application and keep using it to render all your code blocks.

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `config` | [`ExpressiveCodeEngineConfig`](/reference/configuration/) |

#### Methods

##### getBaseStyles()

- <code class="function-signature">**getBaseStyles**(): Promise\<string\></code>

Returns a string containing all CSS styles that should be added to every page using Expressive Code. These styles are static base styles which do not depend on the configured theme(s).

The calling code must take care of actually adding the returned styles to the page.

Please note that the styles contain references to CSS variables, which must also be added to the page. These can be obtained by calling [getThemeStyles](/reference/core-api/#getthemestyles).

##### getJsModules()

- <code class="function-signature">**getJsModules**(): Promise\<string[]\></code>

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

The contents are collected from the `jsModules` property of all registered plugins. Any duplicates are removed.

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.

##### getThemeStyles()

- <code class="function-signature">**getThemeStyles**(): Promise\<string\></code>

Returns a string containing theme-dependent styles that should be added to every page using Expressive Code. These styles contain CSS variable declarations that are generated automatically based on the configured [themes](/reference/configuration/#themes),
[useDarkModeMediaQuery](/reference/configuration/#usedarkmodemediaquery) and
[themeCssSelector](/reference/configuration/#themecssselector) config options.

The first theme defined in the `themes` option is considered the "base theme", for which a full set of CSS variables is declared and scoped to the selector defined by the `themeCssRoot` option (defaults to `:root`).

For all alternate themes, a differential set of CSS variables is declared for cases where their values differ from the base theme, and scoped to theme-specific selectors that are generated by combining `themeCssRoot` with the theme selector specified by this option.

The calling code must take care of actually adding the returned styles to the page.

Please note that these styles must be added to the page together with the base styles returned by [getBaseStyles](/reference/core-api/#getbasestyles).

##### render()

- <code class="function-signature">**render**(input, options?): Promise\<Object\></code>

Renders the given code block(s) and returns the rendered group & block ASTs, the rendered code block contents after all transformations have been applied, and a set of non-global CSS styles required by the rendered code blocks.

In Expressive Code, all processing of your code blocks and their metadata is performed by plugins. To render markup around lines or inline ranges of characters, the `render` method calls the hook functions registered by all added plugins.

###### Arguments

| Parameter | Type | Description |
| :------ | :------ | :------ |
| `input` | [`RenderInput`](/reference/core-api/#renderinput) | The code block(s) to render. Can either be an `ExpressiveCodeBlockOptions` object containing the properties required to create a new `ExpressiveCodeBlock` internally, an existing `ExpressiveCodeBlock`, or an array containing any combination of these. |
| `options`? | [`RenderOptions`](/reference/core-api/#renderoptions) | Optional configuration options for the rendering process. |

###### Returns

`Promise`\<`Object`\>

<dl class="type-declaration-list">
<dt>renderedGroupAst</dt>
<dd>
<PropertySignature>
- Type: `Element`
</PropertySignature>
</dd>
<dt>renderedGroupContents</dt>
<dd>
<PropertySignature>
- Type: `RenderedGroupContents`
</PropertySignature>
</dd>
<dt>styles</dt>
<dd>
<PropertySignature>
- Type: `Set`\<`string`\>
</PropertySignature>
</dd>
</dl>

#### Properties

All config options that can be passed to the constructor are also available on the instance as read-only properties.


## Code blocks

### ExpressiveCodeBlock

Represents a single code block that can be rendered by the Expressive Code engine.

#### Usage example

```js
// codeBlockExample.js
import { ExpressiveCodeBlock } from 'expressive-code'

const codePlaintext = `
// Perform very important calculations
const a = 1 + 2
`

const codeBlock = new ExpressiveCodeBlock({
  code: codePlaintext.trim(),
  language: 'js',
})

// Delete the first line and output the remaining code
codeBlock.deleteLine(0)
console.dir(codeBlock.code)
// --> 'const a = 1 + 2'
```

#### Constructors

##### new ExpressiveCodeBlock(options)

- <code class="function-signature">**new ExpressiveCodeBlock**(options): [ExpressiveCodeBlock](/reference/core-api/#expressivecodeblock)</code>

:::note
You usually don't need to create code blocks manually. Instead, you can pass
`ExpressiveCodeBlockOptions` to the `render` method of the `ExpressiveCodeEngine` class,
and the engine will create the code blocks for you.

Manually creating code blocks may still be useful in some cases, e.g. to allow
integration authors to attach custom annotations to code blocks before passing them
to the engine, or to attach custom data to a code block.
:::

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `options` | [`ExpressiveCodeBlockOptions`](/reference/core-api/#expressivecodeblockoptions) |

#### Methods

##### deleteLine()

- <code class="function-signature">**deleteLine**(index): void</code>

Deletes the line at the given index.

May throw an error if not allowed in the current [state](/reference/core-api/#state).

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `index` | `number` |

##### deleteLines()

- <code class="function-signature">**deleteLines**(indices): void</code>

Deletes the lines at the given indices.

This function automatically sorts the indices in descending order before deleting the lines, so you do not need to worry about indices shifting after deleting a line.

May throw an error if not allowed in the current [state](/reference/core-api/#state).

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `indices` | `number`[] |

##### getLine()

- <code class="function-signature">**getLine**(index): undefined \| [ExpressiveCodeLine](/reference/core-api/#expressivecodeline)</code>

Returns the line at the given index, or `undefined` if the index is out of range.

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `index` | `number` |

##### getLines()

- <code class="function-signature">**getLines**(startIndex?, endIndex?): readonly [ExpressiveCodeLine](/reference/core-api/#expressivecodeline)[]</code>

Returns a readonly array of lines starting at the given index and ending before the given index (exclusive). The indices support the same syntax as JavaScript’s
`Array.slice` method.

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `startIndex`? | `number` |
| `endIndex`? | `number` |

##### insertLine()

- <code class="function-signature">**insertLine**(index, textLine): [ExpressiveCodeLine](/reference/core-api/#expressivecodeline)</code>

Inserts a new line at the given index.

May throw an error if not allowed in the current [state](/reference/core-api/#state).

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `index` | `number` |
| `textLine` | `string` |

##### insertLines()

- <code class="function-signature">**insertLines**(index, textLines): [ExpressiveCodeLine](/reference/core-api/#expressivecodeline)[]</code>

Inserts multiple new lines at the given index.

May throw an error if not allowed in the current [state](/reference/core-api/#state).

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `index` | `number` |
| `textLines` | `string`[] |

#### Accessors

##### code

- <code class="function-signature">**get** **code**(): string</code>

Provides read-only access to the code block's plaintext contents.

##### language

- <code class="function-signature">**get** **language**(): string</code>

- <code class="function-signature">**set** **language**(value): void</code>

Allows getting and setting the code block's language.

Setting this property may throw an error if not allowed in the current [state](/reference/core-api/#state).

###### Parameters

| Parameter | Type |
| :------ | :------ |
| `value` | `string` |

##### locale

- <code class="function-signature">**get** **locale**(): undefined \| string</code>

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

Integrations like `rehype-expressive-code` support multi-language sites by allowing you to provide custom logic to determine a block's locale (e.g. based on its parent document).

If no locale is defined here, `ExpressiveCodeEngine` will render the code block using the `defaultLocale` provided in its configuration.

##### meta

- <code class="function-signature">**get** **meta**(): string</code>

- <code class="function-signature">**set** **meta**(value): void</code>

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

Setting this property may throw an error if not allowed in the current [state](/reference/core-api/#state).

###### Parameters

| Parameter | Type |
| :------ | :------ |
| `value` | `string` |

##### metaOptions

- <code class="function-signature">**get** **metaOptions**(): [MetaOptions](/reference/core-api/#metaoptions-1)</code>

Provides read-only access to the parsed version of the block's [meta](/reference/core-api/#meta) string.

##### parentDocument

- <code class="function-signature">**get** **parentDocument**(): undefined \| Object</code>

Provides read-only access to optional data about the parent document the code block is located in.

Integrations like `rehype-expressive-code` can provide this information based on the source document being processed. There may be cases where no document is available, e.g. when the code block was created dynamically.

##### props

- <code class="function-signature">**get** **props**(): Partial\<[ExpressiveCodeBlockProps](/reference/configuration/#expressivecodeblockprops)\></code>

Provides access to the code block's props.

To allow users to set these props through the meta string, plugins can use the
`preprocessMetadata` hook to read `metaOptions` and update their props accordingly.

Props can be modified until rendering starts and become read-only afterwards.

##### state

- <code class="function-signature">**get** **state**(): undefined \| [ExpressiveCodeProcessingState](/reference/core-api/#expressivecodeprocessingstate)</code>

Provides read-only access to the code block's processing state.

The processing state controls which properties of the code block can be modified. The engine updates it automatically during rendering.

### ExpressiveCodeBlockOptions

#### Properties

##### code

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

The plaintext contents of the code block.

##### language

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

The code block's language.

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

##### locale?

<PropertySignature>
- Type: `string`
</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`](https://expressive-code.com/reference/configuration/#getblocklocale) function, and finally fall back to the configured [`defaultLocale`](https://expressive-code.com/reference/configuration/#defaultlocale).

##### meta?

<PropertySignature>
- Type: `string`
</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.

##### parentDocument?

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

Optional data about the parent document the code block is located in.

Integrations like `rehype-expressive-code` can provide this information based on the source document being processed. There may be cases where no document is available, e.g. when the code block was created dynamically.

###### Object properties

<dl class="type-declaration-list">
<dt>documentRoot</dt>
<dd>
<PropertySignature>
- Type: `unknown`
</PropertySignature>
A reference to the object representing the parsed source document. This reference will stay the same for all code blocks in the same document.

For example, if you are using `rehype-expressive-code` to render code blocks in a Markdown file, this would be the `hast` node representing the file's root node.
</dd>
<dt>positionInDocument</dt>
<dd>
<PropertySignature>
- Type: `Object`
</PropertySignature>
Data about the position of the code block in the parent document.
</dd>
<dt>positionInDocument.groupIndex</dt>
<dd>
<PropertySignature>
- Type: `number`
</PropertySignature>
</dd>
<dt>positionInDocument.totalGroups</dt>
<dd>
<PropertySignature>
- Type: `number`
</PropertySignature>
</dd>
<dt>sourceFilePath</dt>
<dd>
<PropertySignature>
- Type: `string`
</PropertySignature>
The full path to the source file containing the code block.
</dd>
</dl>

##### props?

<PropertySignature>
- Type: Partial\<[ExpressiveCodeBlockProps](/reference/configuration/#expressivecodeblockprops)\>
</PropertySignature>

Optional props that can be used to influence the rendering of this code block.

Plugins can add their own props to this type. To allow users to set these props through the meta string, plugins can use the `preprocessMetadata` hook to read `metaOptions` and update the `props` object accordingly.

### ExpressiveCodeLine

#### Constructors

##### new ExpressiveCodeLine(text)

- <code class="function-signature">**new ExpressiveCodeLine**(text): [ExpressiveCodeLine](/reference/core-api/#expressivecodeline)</code>

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `text` | `string` |

#### Methods

##### addAnnotation()

- <code class="function-signature">**addAnnotation**(annotation): void</code>

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `annotation` | [`ExpressiveCodeAnnotation`](/reference/core-api/#expressivecodeannotation) |

##### deleteAnnotation()

- <code class="function-signature">**deleteAnnotation**(annotation): void</code>

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `annotation` | [`ExpressiveCodeAnnotation`](/reference/core-api/#expressivecodeannotation) |

##### editText()

- <code class="function-signature">**editText**(columnStart, columnEnd, newText): string</code>

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `columnStart` | `undefined` \| `number` |
| `columnEnd` | `undefined` \| `number` |
| `newText` | `string` |

##### getAnnotations()

- <code class="function-signature">**getAnnotations**(): readonly [ExpressiveCodeAnnotation](/reference/core-api/#expressivecodeannotation)[]</code>

#### Accessors

##### parent

- <code class="function-signature">**get** **parent**(): undefined \| [ExpressiveCodeBlock](/reference/core-api/#expressivecodeblock)</code>

- <code class="function-signature">**set** **parent**(value): void</code>

###### Parameters

| Parameter | Type |
| :------ | :------ |
| `value` | `undefined` \| [`ExpressiveCodeBlock`](/reference/core-api/#expressivecodeblock) |

##### text

- <code class="function-signature">**get** **text**(): string</code>

### MetaOptions

#### Constructors

##### new MetaOptions(input)

- <code class="function-signature">**new MetaOptions**(input): [MetaOptions](/reference/core-api/#metaoptions-1)</code>

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `input` | `string` |

#### Methods

##### getBoolean()

- <code class="function-signature">**getBoolean**(key): undefined \| boolean</code>

Returns the last boolean value with the given key (case-insensitive).

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `key` | `string` |

##### getInteger()

- <code class="function-signature">**getInteger**(key): undefined \| number</code>

Returns the last integer value with the given key (case-insensitive), or without a key by passing an empty string.

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `key` | `string` |

##### getIntegers()

- <code class="function-signature">**getIntegers**(keyOrKeys?): number[]</code>

Returns an array of all integer values with the given keys (case-insensitive), or without a key by passing an empty string.

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `keyOrKeys`? | `string` \| `string`[] |

##### getRange()

- <code class="function-signature">**getRange**(key): undefined \| string</code>

Returns the last range value (`{value}`) with the given key (case-insensitive), or without a key by passing an empty string.

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `key` | `string` |

##### getRanges()

- <code class="function-signature">**getRanges**(keyOrKeys?): string[]</code>

Returns an array of all range values (`{value}`) with the given keys (case-insensitive), or without a key by passing an empty string.

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `keyOrKeys`? | `string` \| `string`[] |

##### getRegExp()

- <code class="function-signature">**getRegExp**(key): undefined \| RegExp</code>

Returns the last RegExp value (`/value/`) with the given key (case-insensitive), or without a key by passing an empty string.

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `key` | `string` |

##### getRegExps()

- <code class="function-signature">**getRegExps**(keyOrKeys?): RegExp[]</code>

Returns an array of all RegExp values (`/value/`) with the given keys (case-insensitive), or without a key by passing an empty string.

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `keyOrKeys`? | `string` \| `string`[] |

##### getString()

- <code class="function-signature">**getString**(key): undefined \| string</code>

Returns the last string value with the given key (case-insensitive), or without a key by passing an empty string.

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `key` | `string` |

##### getStrings()

- <code class="function-signature">**getStrings**(keyOrKeys?): string[]</code>

Returns an array of all string values with the given keys (case-insensitive), or without a key by passing an empty string.

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `keyOrKeys`? | `string` \| `string`[] |

##### list()

- <code class="function-signature">**list**\<K\>(keyOrKeys?, kind?): ReturnType</code>

Returns a list of meta options, optionally filtered by their key and/or MetaOptionKind.

###### Type parameters

| Parameter | Value |
| :------ | :------ |
| `K` extends `undefined` \| `"string"` \| `"boolean"` \| `"range"` \| `"regexp"` | `undefined` |

###### Arguments

| Parameter | Type | Description |
| :------ | :------ | :------ |
| `keyOrKeys`? | `string` \| `string`[] | Allows to filter the options by key. An empty string will return options without a key. A non-empty string will return options with a matching key (case-insensitive). An array of strings will return options with any of the matching keys. If omitted, no key-based filtering will be applied. |
| `kind`? | `K` | Allows to filter the options by MetaOptionKind. If omitted, no kind-based filtering will be applied. |

##### value()

- <code class="function-signature">**value**\<K\>(key, kind?): undefined \| OptionType\["value"\]</code>

###### Type parameters

| Parameter | Value |
| :------ | :------ |
| `K` extends `undefined` \| `"string"` \| `"boolean"` \| `"range"` \| `"regexp"` | `undefined` |

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `key` | `string` |
| `kind`? | `K` |

#### Accessors

##### errors

- <code class="function-signature">**get** **errors**(): undefined \| string[]</code>

A list of error messages that occurred when parsing the meta string, or `undefined` if no errors occurred.

## Themes

### ExpressiveCodeTheme

#### Constructors

##### new ExpressiveCodeTheme(theme)

- <code class="function-signature">**new ExpressiveCodeTheme**(theme): [ExpressiveCodeTheme](/reference/core-api/#expressivecodetheme)</code>

Loads the given theme for use with Expressive Code. Supports both Shiki and VS Code themes.

You can also pass an existing `ExpressiveCodeTheme` instance to create a copy of it.

Note: To save on bundle size, this constructor does not support loading themes bundled with Shiki by name (e.g. `dracula`). Instead, import Shiki's `loadTheme` function yourself, use it to load its bundled theme (e.g. `themes/dracula.json`), and pass the result to this constructor.

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `theme` | `ExpressiveCodeThemeInput` |

#### Methods

##### applyHueAndChromaAdjustments()

- <code class="function-signature">**applyHueAndChromaAdjustments**(adjustments): [ExpressiveCodeTheme](/reference/core-api/#expressivecodetheme)</code>

Applies chromatic adjustments to entire groups of theme colors while keeping their relative lightness and alpha components intact. This can be used to quickly create theme variants that fit the color scheme of any website or brand.

Adjustments can either be defined as hue and chroma values in the OKLCH color space (range 0–360 for hue, 0–0.4 for chroma), or these values can be extracted from hex color strings (e.g. `#3b82f6`).

You can target predefined groups of theme colors (e.g. `backgrounds`, `accents`) and/or use the `custom` property to define your own groups of theme colors to be adjusted. Each custom group must contain a `themeColorKeys` property with an array of VS Code theme color keys (e.g. `['panel.background', 'panel.border']`) and a `targetHueAndChroma` property that accepts the same adjustment target values as `backgrounds` and `accents`. Custom groups will be applied in the order they are defined.

Returns the same `ExpressiveCodeTheme` instance to allow chaining.

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `adjustments` | `Object` |
| `adjustments.accents`? | `string` \| [`ChromaticRecolorTarget`](/reference/core-api/#chromaticrecolortarget) |
| `adjustments.backgrounds`? | `string` \| [`ChromaticRecolorTarget`](/reference/core-api/#chromaticrecolortarget) |
| `adjustments.custom`? | `Object`[] |

##### ensureMinSyntaxHighlightingColorContrast()

- <code class="function-signature">**ensureMinSyntaxHighlightingColorContrast**(minContrast, backgroundColor?): [ExpressiveCodeTheme](/reference/core-api/#expressivecodetheme)</code>

Processes the theme's syntax highlighting colors to ensure a minimum contrast ratio between foreground and background colors.

The default value of 5.5 ensures optimal accessibility with a contrast ratio of 5.5:1.

You can optionally pass a custom background color to use for the contrast checks. By default, the theme's background color will be used.

Returns the same `ExpressiveCodeTheme` instance to allow chaining.

###### Arguments

| Parameter | Type | Default value |
| :------ | :------ | :------ |
| `minContrast` | `number` | `5.5` |
| `backgroundColor`? | `string` | `undefined` |

##### fromJSONString()

- <code class="function-signature">**static** **fromJSONString**(json): [ExpressiveCodeTheme](/reference/core-api/#expressivecodetheme)</code>

Attempts to parse the given JSON string as a theme.

As some themes follow the JSONC format and may contain comments and trailing commas, this method will attempt to strip them before parsing the result.

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `json` | `string` |

#### Properties

##### bg

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

##### colors

<PropertySignature>
- Type: `Object` (mapping VS Code workbench color keys to values)
</PropertySignature>

##### fg

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

##### name

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

##### semanticHighlighting

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

##### settings

<PropertySignature>
- Type: [`ThemeSetting`](/reference/core-api/#themesetting)[]
</PropertySignature>

##### styleOverrides

An optional set of style overrides that can be used to customize the appearance
of the rendered code blocks without having to write custom CSS.

See [Overriding Styles](/reference/style-overrides) for a list of all available settings.

##### type

<PropertySignature>
- Type: `"dark"` \| `"light"`
</PropertySignature>

## Annotations

In Expressive Code, annotations are used by plugins to attach semantic information to lines or inline ranges of code. They are used to represent things like syntax highlighting, text markers, comments, errors, warnings, and other semantic information.

Annotations must provide a `render` function that transforms its contained AST nodes, e.g. by wrapping them in HTML tags. This function is called by the engine when it's time to render the line the annotation has been attached to.

### ExpressiveCodeAnnotation

An abstract class representing a single annotation attached to a code line.

You can develop your own annotations by extending this class and providing implementations for its abstract methods. See the implementation of the
[InlineStyleAnnotation](/reference/core-api/#inlinestyleannotation) class for an example.

You can also define your annotations as plain objects, as long as they have the same properties as this class. This allows you to use annotations in a more functional way, without the need to extend a class.

#### Constructors

:::note
As an abstract class, `ExpressiveCodeAnnotation` cannot be instantiated directly. You should create a subclass that extends `ExpressiveCodeAnnotation` instead.
:::

#### Methods

##### `abstract` render()

- <code class="function-signature">**abstract** **render**(options): Parents[]</code>

Renders the annotation by transforming the provided nodes.

This function will be called with an array of AST nodes to transform, and is expected to return an array containing the same number of nodes.

For example, you could use the `hastscript` library to wrap the received nodes in HTML elements.

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `options` | [`AnnotationRenderOptions`](/reference/core-api/#annotationrenderoptions) |

#### Properties

All annotation base options are available on the instance as read-only properties. See [`AnnotationBaseOptions`](#annotationbaseoptions) for the entire list.


### InlineStyleAnnotation

A theme-dependent inline style annotation that allows changing colors, font styles and decorations of the targeted code. This annotation is used by the syntax highlighting plugin to apply colors and styles to syntax tokens, and you can use it in your own plugins as well.

You can add as many inline style annotations to a line as you want, even targeting the same code with multiple fully or partially overlapping annotation ranges. During rendering, these annotations will be automatically optimized to avoid creating unnecessary HTML elements.

:::note
If you want to publish your own plugin using the `InlineStyleAnnotation` class, import it from the `@expressive-code/core` package installed as a **peer dependency** of your plugin package. This ensures that your plugin does not cause a version conflict if the user has a different version of Expressive Code installed on their site.
:::

#### Usage example

In the following example, we create a plugin that makes the first word of each code block red in the first theme. We do this by adding an `InlineStyleAnnotation` to the first line of each code block.

import pluginFirstWordRedCode from '/plugins/plugin-first-word-red.js?raw'

<Code code={pluginFirstWordRedCode.replace(/\t/g, '  ')} lang="js" title="plugins/plugin-first-word-red.js" />

After adding this plugin to your configuration, you can use it like this:

````
```js first-word-red
consule.log('Hello world!')
```
````

The rendered code block will now have a red text color applied to the first word, but only in the dark theme (the first theme in the configuration):

```js first-word-red
consule.log('Hello world!')
```

#### Constructors

##### new InlineStyleAnnotation(options)

- <code class="function-signature">**new InlineStyleAnnotation**(options): [InlineStyleAnnotation](/reference/core-api/#inlinestyleannotation)</code>

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `options` | [`InlineStyleAnnotationOptions`](/reference/core-api/#inlinestyleannotationoptions) |

#### Methods

##### render()

- <code class="function-signature">**render**(options): Parents[]</code>

Renders the annotation by transforming the provided nodes.

This function will be called with an array of AST nodes to transform, and is expected to return an array containing the same number of nodes.

For example, you could use the `hastscript` library to wrap the received nodes in HTML elements.

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `options` | [`AnnotationRenderOptions`](/reference/core-api/#annotationrenderoptions) |

#### Properties

All config options that can be passed to the constructor are also available on the instance as read-only properties.

See [`InlineStyleAnnotationOptions`](#inlinestyleannotationoptions) for the entire list.


## Asset functions

### createInlineSvgUrl

- <code class="function-signature">**createInlineSvgUrl**(svgContents, options): string</code>

Creates an inline SVG image data URL from the given contents of an SVG file.

You can use it to embed SVG images directly into a plugin's styles or HAST, or pass it to an existing `styleOverrides` icon setting.

The optional `options` argument allows further customization of the generated URL.

#### Arguments

| Parameter | Type |
| :------ | :------ |
| `svgContents` | `string` \| `string`[] |
| `options` | [`CreateInlineSvgUrlOptions`](/reference/core-api/#createinlinesvgurloptions) |

## Color analysis functions

### getColorContrast

- <code class="function-signature">**getColorContrast**(color1, color2): number</code>

#### Arguments

| Parameter | Type |
| :------ | :------ |
| `color1` | `string` |
| `color2` | `string` |

### getColorContrastOnBackground

- <code class="function-signature">**getColorContrastOnBackground**(input, background): number</code>

#### Arguments

| Parameter | Type |
| :------ | :------ |
| `input` | `string` |
| `background` | `string` |

### getFirstStaticColor

- <code class="function-signature">**getFirstStaticColor**(...inputs): undefined \| string</code>

Given any number of input colors, which may include CSS variables with optional fallbacks, returns the first static color.

Returns `undefined` if no parseable static color can be found.

#### Arguments

| Parameter | Type |
| :------ | :------ |
| ...`inputs` | (`undefined` \| `string`)[] |

### getLuminance

- <code class="function-signature">**getLuminance**(input): number</code>

Returns the luminance of a color. Luminance values are between 0 and 1.

#### Arguments

| Parameter | Type |
| :------ | :------ |
| `input` | `string` |

### getStaticBackgroundColor

- <code class="function-signature">**getStaticBackgroundColor**(styleVariant): string</code>

Determine a static background color based on the given style variant, trying to resolve fallback values of CSS variables if necessary.

This color is intended to be used for contrast calculations, not as an actual background color.

#### Arguments

| Parameter | Type |
| :------ | :------ |
| `styleVariant` | [`StyleVariant`](/reference/plugin-api/#stylevariant) |

## Color manipulation functions

### changeAlphaToReachColorContrast

- <code class="function-signature">**changeAlphaToReachColorContrast**(input, background, minContrast, maxContrast): string</code>

#### Arguments

| Parameter | Type | Default value |
| :------ | :------ | :------ |
| `input` | `string` | `undefined` |
| `background` | `string` | `undefined` |
| `minContrast` | `number` | `6` |
| `maxContrast` | `number` | `22` |

### changeLuminanceToReachColorContrast

- <code class="function-signature">**changeLuminanceToReachColorContrast**(input1, input2, minContrast): string</code>

#### Arguments

| Parameter | Type | Default value |
| :------ | :------ | :------ |
| `input1` | `string` | `undefined` |
| `input2` | `string` | `undefined` |
| `minContrast` | `number` | `6` |

### darken

- <code class="function-signature">**darken**(input, amount): string</code>

Darkens a color by the given amount. Automatically limits the resulting lightness value to the range 0 to 1.

#### Arguments

| Parameter | Type |
| :------ | :------ |
| `input` | `string` |
| `amount` | `number` |

### ensureColorContrastOnBackground

- <code class="function-signature">**ensureColorContrastOnBackground**(input, background, minContrast, maxContrast): string</code>

Modifies the luminance and/or the alpha value of a color to ensure its color contrast on the given background color is within the given range.

- If the contrast is too low, the luminance is either increased or decreased first, and then the alpha value is increased (if required).
- If the contrast is too high, only the alpha value is decreased.

If the target contrast cannot be reached, the function will try to get as close as possible.

#### Arguments

| Parameter | Type | Default value |
| :------ | :------ | :------ |
| `input` | `string` | `undefined` |
| `background` | `string` | `undefined` |
| `minContrast` | `number` | `5.5` |
| `maxContrast` | `number` | `22` |

### lighten

- <code class="function-signature">**lighten**(input, amount): string</code>

Lightens a color by the given amount. Automatically limits the resulting lightness value to the range 0 to 1.

#### Arguments

| Parameter | Type |
| :------ | :------ |
| `input` | `string` |
| `amount` | `number` |

### mix

- <code class="function-signature">**mix**(input, mixinInput, amount): string</code>

Mixes the second color into the first color by the given amount. Amount should be between 0 and 1.

#### Arguments

| Parameter | Type |
| :------ | :------ |
| `input` | `string` |
| `mixinInput` | `string` |
| `amount` | `number` |

### multiplyAlpha

- <code class="function-signature">**multiplyAlpha**(input, factor): string</code>

Multiplies the existing alpha value of a color with the given factor. Automatically limits the resulting alpha value to the range 0 to 1.

#### Arguments

| Parameter | Type |
| :------ | :------ |
| `input` | `string` |
| `factor` | `number` |

### onBackground

- <code class="function-signature">**onBackground**(input, background): string</code>

Computes how the first color would look on top of the second color.

#### Arguments

| Parameter | Type |
| :------ | :------ |
| `input` | `string` |
| `background` | `string` |

### setAlpha

- <code class="function-signature">**setAlpha**(input, newAlpha): string</code>

Overrides the alpha value of a color with the given value. Values should be between 0 and 1.

#### Arguments

| Parameter | Type |
| :------ | :------ |
| `input` | `string` |
| `newAlpha` | `number` |

### setLuminance

- <code class="function-signature">**setLuminance**(input, targetLuminance): string</code>

Mixes a color with white or black to achieve the desired luminance. Luminance values should be between 0 and 1.

#### Arguments

| Parameter | Type |
| :------ | :------ |
| `input` | `string` |
| `targetLuminance` | `number` |

## Referenced types

### AnnotationBaseOptions

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

#### Object properties

<dl class="type-declaration-list">
<dt>inlineRange</dt>
<dd>
<PropertySignature>
- Type: [`ExpressiveCodeInlineRange`](/reference/core-api/#expressivecodeinlinerange)
</PropertySignature>
</dd>
<dt>renderPhase</dt>
<dd>
<PropertySignature>
- Type: [`AnnotationRenderPhase`](/reference/core-api/#annotationrenderphase)
</PropertySignature>
</dd>
</dl>

### AnnotationRenderOptions

<PropertySignature>
- Type: [`ResolverContext`](/reference/plugin-api/#resolvercontext) & `Object`
</PropertySignature>

#### Object properties

<dl class="type-declaration-list">
<dt>line</dt>
<dd>
<PropertySignature>
- Type: [`ExpressiveCodeLine`](/reference/core-api/#expressivecodeline)
</PropertySignature>
</dd>
<dt>lineIndex</dt>
<dd>
<PropertySignature>
- Type: `number`
</PropertySignature>
</dd>
<dt>nodesToTransform</dt>
<dd>
<PropertySignature>
- Type: `Parents`[]
</PropertySignature>
</dd>
</dl>

### AnnotationRenderPhase

<PropertySignature>
- Type: `"earliest"` \| `"earlier"` \| `"normal"` \| `"later"` \| `"latest"`
</PropertySignature>

### ChromaticRecolorTarget

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

#### Object properties

<dl class="type-declaration-list">
<dt>chroma</dt>
<dd>
<PropertySignature>
- Type: `number`
</PropertySignature>
The target chroma (0 – 0.4).

If the input color's lightness is very high, the resulting chroma may be lower than this value. This avoids results that appear too saturated in comparison to the input color.
</dd>
<dt>hue</dt>
<dd>
<PropertySignature>
- Type: `number`
</PropertySignature>
The target hue in degrees (0 – 360).
</dd>
<dt>chromaMeasuredAtLightness</dt>
<dd>
<PropertySignature>
- Type: `number`
</PropertySignature>
The lightness (0 – 1) that the target chroma was measured at.

If given, the chroma will be adjusted relative to this lightness before applying it to the input color.
</dd>
</dl>

### CreateInlineSvgUrlOptions

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

#### Object properties

<dl class="type-declaration-list">
<dt>keepSize</dt>
<dd>
<PropertySignature>
- Type: `boolean`
</PropertySignature>
Whether to keep the original size of the SVG image.

By default, any `width` and `height` attributes inside the SVG tag are removed.

</dd>
</dl>

### ExpressiveCodeInlineRange

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

#### Object properties

<dl class="type-declaration-list">
<dt>columnEnd</dt>
<dd>
<PropertySignature>
- Type: `number`
</PropertySignature>
</dd>
<dt>columnStart</dt>
<dd>
<PropertySignature>
- Type: `number`
</PropertySignature>
</dd>
</dl>

### ExpressiveCodeProcessingState

#### Properties

##### canEditAnnotations

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

##### canEditCode

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

##### canEditLanguage

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

##### canEditMetadata

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

### InlineStyleAnnotationOptions

<PropertySignature>
- Type: [`AnnotationBaseOptions`](/reference/core-api/#annotationbaseoptions) & `Object`
</PropertySignature>

#### Object properties

<dl class="type-declaration-list">
<dt>bgColor</dt>
<dd>
<PropertySignature>
- Type: `string`
</PropertySignature>
The background color of the annotation. This is expected to be a hex color string, e.g. `#888`. Using CSS variables or other color formats is possible, but prevents automatic color contrast checks from working.
</dd>
<dt>bold</dt>
<dd>
<PropertySignature>
- Type: `boolean`
</PropertySignature>
Whether the annotation should be rendered in bold.
</dd>
<dt>color</dt>
<dd>
<PropertySignature>
- Type: `string`
</PropertySignature>
The color of the annotation. This is expected to be a hex color string, e.g. `#888`. Using CSS variables or other color formats is possible, but prevents automatic color contrast checks from working.
</dd>
<dt>italic</dt>
<dd>
<PropertySignature>
- Type: `boolean`
</PropertySignature>
Whether the annotation should be rendered in italics.
</dd>
<dt>strikethrough</dt>
<dd>
<PropertySignature>
- Type: `boolean`
</PropertySignature>
Whether the annotation should be rendered with a strikethrough.
</dd>
<dt>styleVariantIndex</dt>
<dd>
<PropertySignature>
- Type: `number`
</PropertySignature>
Inline styles can be theme-dependent, which allows plugins like syntax highlighters to style the same code differently depending on the theme.

To support this, the engine creates a style variant for each theme given in the configuration, and plugins can go through the engine's `styleVariants` array to access all the themes.

When adding an inline style annotation to a range of code, you can optionally set this property to a `styleVariants` array index to indicate that this annotation only applies to a specific theme. If this property is not set, the annotation will apply to all themes.
</dd>
<dt>underline</dt>
<dd>
<PropertySignature>
- Type: `boolean`
</PropertySignature>
Whether the annotation should be rendered with an underline.
</dd>
</dl>

### RenderInput

<PropertySignature>
- Type: [`ExpressiveCodeBlockOptions`](/reference/core-api/#expressivecodeblockoptions) \| [`ExpressiveCodeBlock`](/reference/core-api/#expressivecodeblock) \| ([`ExpressiveCodeBlockOptions`](/reference/core-api/#expressivecodeblockoptions) \| [`ExpressiveCodeBlock`](/reference/core-api/#expressivecodeblock))[]
</PropertySignature>

### RenderOptions

#### Properties

##### onInitGroup?

<PropertySignature>
- Type: (`groupContents`) => `void`
</PropertySignature>

An optional handler function that can initialize plugin data for the code block group before processing starts.

Plugins can provide access to their data by exporting a const set to a `new AttachedPluginData(...)` instance (e.g. `myPluginData`).

You can then import the const and set `onInitGroup` to a function that calls `myPluginData.setFor(group, { ...data... })`.

###### Arguments

| Parameter | Type |
| :------ | :------ |
| `groupContents` | readonly \{ `codeBlock`: `ExpressiveCodeBlock` \}[] |

### ThemeSetting

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

#### Object properties

<dl class="type-declaration-list">
<dt>settings</dt>
<dd>
<PropertySignature>
- Type: `Object`
</PropertySignature>
</dd>
<dt>settings.fontStyle</dt>
<dd>
<PropertySignature>
- Type: `string`
</PropertySignature>
</dd>
<dt>settings.foreground</dt>
<dd>
<PropertySignature>
- Type: `string`
</PropertySignature>
</dd>
<dt>name</dt>
<dd>
<PropertySignature>
- Type: `string`
</PropertySignature>
</dd>
<dt>scope</dt>
<dd>
<PropertySignature>
- Type: `string`[]
</PropertySignature>
</dd>
</dl>
