---
# 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: Editor & Terminal Frames
---

import PropertySignature from '@components/PropertySignature.astro'
import ConfigVariants from '@components/ConfigVariants.astro'
import { Tabs, TabItem } from '@astrojs/starlight/components'

Expressive Code supports rendering frames around your code blocks. By default, the type of frame (editor window or terminal window) is selected automatically based on the language identifier in your code block's opening fence.

Frames can have optional titles, which are either taken from the code block's meta string, or from a file name comment in the first lines of the code.

:::tip[No installation required]
These features are provided by `@expressive-code/plugin-frames`, which is installed & enabled by default in all framework integrations. You can start using it right away in your documents!
:::

## Usage in markdown / MDX

### Code editor frames

To make code blocks look like an editor window similar to VS Code, you must provide a file name that can be displayed in the open file tab.

To do this, you can either set the `title` attribute in the opening code fence to a file name, or add a [file name comment](#file-name-comments) to the first lines of the code.

See the markdown code below for examples of both methods:

````md title="editor-example.md" ins=/title=".*?"/ ins=/<!--.*?-->/
```js title="my-test-file.js"
console.log('Title attribute example')
```

```html
<!-- src/content/index.html -->
<div>File name comment example</div>
```
````

The rendered result looks like this:

```js title="my-test-file.js"
console.log('Title attribute example')
```

```html
<!-- src/content/index.html -->
<div>File name comment example</div>
```

### Terminal frames

When encountering code blocks with a language identifier that is typically used for terminal sessions or shell scripts (`ansi`, `bash`, `bat`, `batch`, `cmd`, `console`, `powershell`, `ps`, `ps1`, `psd1`, `psm1`, `sh`, `shell`, `shellscript`, `shellsession`, `zsh`), Expressive Code performs additional checks to detect the frame type to use:

- If the code block contains a shell script file name in the `title` attribute of the opening code fence or a [file name comment](#file-name-comments), or if the code starts with a shebang (`#!`), it is considered to be a script file instead of a terminal session, and is rendered with a code editor frame if a file name was provided, or as a plain code block otherwise.
- In all other cases, the code block is considered to be a terminal session and rendered with a terminal frame.

In contrast to code editor frames, terminal frames do not require a title. The title bar will always be rendered, and you can optionally add a title using the `title` attribute:

````md ins=/title=".*?"/
```bash
echo "This terminal frame has no title"
```

```powershell title="PowerShell terminal example"
Write-Output "This one has a title!"
```
````

The rendered result looks like this:

```bash
echo "This frame has no title"
```

```powershell title="PowerShell terminal example"
Write-Output "This one has a title!"
```

### File name comments

If a code block does not have a `title` attribute, Expressive Code supports automatically extracting a title from a file name comment inside your code.

The following conditions must be met for a comment to be recognized as a file name comment:

- It must appear within the first 4 lines of the code block.
- Its line must start with `//`, `<!--`, `/*` or `#`, but not `#!`. Although not required, we recommend using the comment syntax matching your code block's language.
- It can optionally have a prefix that ends with a colon (`:`). This allows you to prefix the file name with some text: `// File name: index.js`
- The file name appears to be valid in the context of the code block's language. For example, a comment containing a CSS file name in a JavaScript code block will be ignored.

Once a file name comment is found, it is removed from the code block's content, and the extracted file name is used as the code block's title.

:::note
You can prevent automatic file name comment extraction using any of the following options:
- Provide a `title` in the opening code fence
- [Set the frame type](#overriding-frame-types) of the code block to `none`
- Disable it globally by setting `extractFileNameFromCode` to `false` in the configuration
:::

### Overriding frame types

If you want to override the automatic frame type detection for some code blocks, you can add the `frame="..."` attribute to the opening code fence.

The supported values for this attribute are `code`, `terminal`, `none` and `auto`. The default value is `auto`.

:::tip
Setting the frame type to `none` can reduce visual clutter when showing many single-line terminal blocks on a page, e.g. in a tutorial.
:::

````md ins=/frame=".*?"/
```sh frame="none"
echo "Look ma, no frame!"
```

```ps frame="code" title="PowerShell Profile.ps1"
# Without overriding, this would be a terminal frame
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
New-Alias tail Watch-Tail
```
````

The rendered result looks like this:

```sh frame="none"
echo "Look ma, no frame!"
```

```ps frame="code" title="PowerShell Profile.ps1"
# Without overriding, this would be a terminal frame
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
New-Alias tail Watch-Tail
```

## Usage in the `<Code>` component

The frames plugin adds multiple props to the `<Code>` component that allow direct access to its features. The following props are available:

### Props

#### frame

<PropertySignature>
- Type: `"terminal"` \| `"code"` \| `"none"` \| `"auto"`
- Default: `auto`
</PropertySignature>

Allows you to override the automatic frame type detection for a code block.

The supported values are `code`, `terminal`, `none` and `auto`.

#### title

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

The code block's title. For terminal frames, this is displayed as the terminal window title, and for code frames, it's displayed as the file name in an open file tab.

If no title is given, the plugin will try to automatically extract a title from a [file name comment](https://expressive-code.com/key-features/frames/#file-name-comments) inside your code, unless disabled by the `extractFileNameFromCode` option.

## Configuration

When using this plugin through a framework integration, you can configure it by passing options to the integration.

In addition, you can also override its default styles by adding a `frames` object to the `styleOverrides` engine config option. You can find a list of all [overridable styles](#available-style-overrides) below.

Here are configuration examples for some popular site generators:

<ConfigVariants
  settings={`
    // You can optionally override the plugin's default settings here
    frames: {
      // Example: Hide the "Copy to clipboard" button
      showCopyToClipboardButton: false,
    },
    styleOverrides: {
      // You can optionally override the plugin's default styles here
      frames: {
        shadowColor: '#124',
      },
    },
  `}
/>

### Available plugin options

You can configure the plugin's features using the following options:

#### extractFileNameFromCode

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

If `true`, and no title was found in the code block's meta string, the plugin will try to find and extract a comment line containing the code block file name from the first 4 lines of the code.

#### removeCommentsWhenCopyingTerminalFrames

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

If `true`, the "Copy to clipboard" button of terminal window frames will remove comment lines starting with `#` from the copied text.

This is useful to reduce the copied text to the actual commands users need to run, instead of also copying explanatory comments or instructions.

#### showCopyToClipboardButton

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

If `true`, a "Copy to clipboard" button will be shown for each code block.

### Available style overrides

This plugin adds a `frames` object to the `styleOverrides` engine config option, allowing you to customize the visual appearance of the rendered frames. The object contains the following properties:

#### copyIcon

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
</PropertySignature>

An inline SVG URL for the copy to clipboard icon.

Expects a string in the format `url("data:image/svg+xml,...")`, which can be generated from the contents of an SVG file using [createInlineSvgUrl](/reference/core-api/#createinlinesvgurl).

#### editorActiveTabBackground

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ theme }) => theme.colors['tab.activeBackground']``
</PropertySignature>

The CSS `background` value for the active editor tab.

#### editorActiveTabBorderColor

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``'transparent'``
</PropertySignature>

The border color of the active editor tab.

#### editorActiveTabForeground

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ theme }) => theme.colors['tab.activeForeground']``
</PropertySignature>

The foreground color of the active editor tab.

#### editorActiveTabIndicatorBottomColor

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ theme }) => theme.colors['tab.activeBorder']``
</PropertySignature>

The color of the indicator line displayed at the bottom border of the active editor tab.

#### editorActiveTabIndicatorHeight

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ resolveSetting }) => resolveSetting('borderWidth')``
</PropertySignature>

The height of the indicator lines highlighting the active editor tab. These are colorful lines that appear at the top and/or bottom of the active tab.

The individual line colors can be set in [editorActiveTabIndicatorTopColor](#editoractivetabindicatortopcolor) and
[editorActiveTabIndicatorBottomColor](#editoractivetabindicatorbottomcolor).

#### editorActiveTabIndicatorTopColor

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ theme }) => theme.colors['tab.activeBorderTop']``
</PropertySignature>

The color of the indicator line displayed at the top border of the active editor tab.

#### editorBackground

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ resolveSetting }) => resolveSetting('codeBackground')``
</PropertySignature>

The background color of the code editor. This color is used for the "code" frame type.

#### editorTabBarBackground

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ theme }) => theme.colors['editorGroupHeader.tabsBackground']``
</PropertySignature>

The CSS `background` value of the editor tab bar.

#### editorTabBarBorderBottomColor

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ theme }) => theme.colors['editorGroupHeader.tabsBorder'] || 'transparent'``
</PropertySignature>

The color of the bottom border of the editor tab bar. This is an additional border that can be used to display a line between the editor tab bar and the code contents.

#### editorTabBarBorderColor

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ resolveSetting }) => resolveSetting('borderColor')``
</PropertySignature>

The border color of the editor tab bar.

#### editorTabBorderRadius

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ resolveSetting }) => resolveSetting('borderRadius')``
</PropertySignature>

The border radius to apply to the outer corners of editor tabs.

#### editorTabsMarginBlockStart

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``'0'``
</PropertySignature>

The block margin (= top margin in horizontal writing mode) to apply inside the tab bar before the editor tabs.

#### editorTabsMarginInlineStart

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``'0'``
</PropertySignature>

The inline margin (= left margin in horizontal writing mode) to apply inside the tab bar before the first editor tab.

#### frameBoxShadowCssValue

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ resolveSetting }) => `0.1rem 0.1rem 0.2rem ${resolveSetting('frames.shadowColor')}` ``
</PropertySignature>

The CSS value for the box shadow of the frame.

#### inlineButtonBackground

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ resolveSetting }) => resolveSetting('frames.inlineButtonForeground')``
</PropertySignature>

The background color of the copy button. This color is modified by the state-dependent opacity values specified in
[inlineButtonBackgroundIdleOpacity](#inlinebuttonbackgroundidleopacity), [inlineButtonBackgroundHoverOrFocusOpacity](#inlinebuttonbackgroundhoverorfocusopacity) and [inlineButtonBackgroundActiveOpacity](#inlinebuttonbackgroundactiveopacity).

#### inlineButtonBackgroundActiveOpacity

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``'0.3'``
</PropertySignature>

The opacity of the copy button background when pressed.

#### inlineButtonBackgroundHoverOrFocusOpacity

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``'0.2'``
</PropertySignature>

The opacity of the copy button background when hovered or focused.

#### inlineButtonBackgroundIdleOpacity

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``'0'``
</PropertySignature>

The opacity of the copy button background when idle.

#### inlineButtonBorder

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ resolveSetting }) => resolveSetting('frames.inlineButtonForeground')``
</PropertySignature>

The border color of the copy button.

#### inlineButtonBorderOpacity

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``'0.4'``
</PropertySignature>

The opacity of the copy button border.

#### inlineButtonForeground

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ resolveSetting }) => resolveSetting('codeForeground')``
</PropertySignature>

The foreground color of the copy button.

#### shadowColor

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ theme, resolveSetting }) => theme.colors['widget.shadow'] || multiplyAlpha(resolveSetting('borderColor'), 0.75)``
</PropertySignature>

The color to use for the shadow of the frame.

#### terminalBackground

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ theme }) => theme.colors['terminal.background']``
</PropertySignature>

The background color of the terminal window. This color is used for the "terminal" frame type.

#### terminalIcon

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
</PropertySignature>

An inline SVG URL for the terminal icon.

Expects a string in the format `url("data:image/svg+xml,...")`, which can be generated from the contents of an SVG file using [createInlineSvgUrl](/reference/core-api/#createinlinesvgurl).

Defaults to three dots in a row.

#### terminalTitlebarBackground

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ theme }) => theme.colors['titleBar.activeBackground'] || theme.colors['editorGroupHeader.tabsBackground']``
</PropertySignature>

The background color of the terminal title bar.

#### terminalTitlebarBorderBottomColor

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``  theme.colors['titleBar.border'] ||
  onBackground(resolveSetting('borderColor'), theme.type === 'dark' ? '#000000bf' : '#ffffffbf')``
</PropertySignature>

The color of the border between the terminal title bar and the terminal contents.

#### terminalTitlebarDotsForeground

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ resolveSetting }) => resolveSetting('frames.terminalTitlebarForeground')``
</PropertySignature>

The color of the three dots in the terminal title bar.

#### terminalTitlebarDotsOpacity

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``'0.15'``
</PropertySignature>

The opacity of the three dots in the terminal title bar.

#### terminalTitlebarForeground

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ theme }) => theme.colors['titleBar.activeForeground']``
</PropertySignature>

The foreground color of the terminal title bar.

#### tooltipSuccessBackground

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ theme }) => setLuminance(theme.colors['terminal.ansiGreen'] || '#0dbc79', 0.18)``
</PropertySignature>

The background color of the tooltip shown after successfully copying the code.

#### tooltipSuccessForeground

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``'white'``
</PropertySignature>

The foreground color of the tooltip shown after successfully copying the code.
