---
# 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: Collapsible Sections
---

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

This optional plugin allows you to reduce long code examples to their relevant parts by collapsing any line ranges that are not relevant to the example.

The lines of collapsed sections will be replaced by a clickable `X collapsed lines` element. When clicked, the collapsed section will be expanded, showing the previously hidden lines.

## Installation

Before being able to use collapsible sections in your code blocks, you need to install the plugin as a dependency and add it to your configuration:

<Steps>

1. Add the package to your site's dependencies:

    <PackageManagers pkg="@expressive-code/plugin-collapsible-sections" />

2. Add the plugin to your site's configuration by passing it in the `plugins` list.

    In Astro and Starlight projects, we recommend putting this option in `ec.config.mjs` to ensure that the [`<Code>` component](/key-features/code-component/#using-an-ecconfigmjs-file) can still be used on your site.

    <ConfigVariants
      preferEcConfigFile
      imports={`
        import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections'
      `}
      settings={`
        plugins: [pluginCollapsibleSections()],
      `}
    />

</Steps>

## Usage in markdown / MDX

To mark a section as collapsible, you need to add **meta information** to your code blocks. This is done by appending `collapse={X-Y}` to your opening code fence, indicating a collapsed section from line `X` to (and including) line `Y`.

You can also collapse multiple sections in a single code block by separating them with commas:

export const exampleCode = `
// All this boilerplate setup code will be collapsed
import { someBoilerplateEngine } from '@example/some-boilerplate'
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'

const engine = someBoilerplateEngine(evenMoreBoilerplate())

// This part of the code will be visible by default
engine.doSomething(1, 2, 3, calcFn)

function calcFn() {
  // You can have multiple collapsed sections
  const a = 1
  const b = 2
  const c = a + b

  // This will remain visible
  console.log(\`Calculation result: \${a} + \${b} = \${c}\`)
  return c
}

// All this code until the end of the block will be collapsed again
engine.closeConnection()
engine.freeMemory()
engine.shutdown({ reason: 'End of example boilerplate code' })
`

export const exampleMeta = `collapse={1-5, 12-14, 21-24}`

<Code lang="md" code={'```js ' + exampleMeta + exampleCode + '```'} meta={`ins="${exampleMeta}"`} />

### Available styles

The plugin supports different section styles, which can be set per block using the `collapseStyle` prop:

<Code lang="md" code={'```js ' + exampleMeta + ' collapseStyle=<your style here>\n// ...\n```'} meta={`ins="collapseStyle=<your style here>"`} />

You can also change the prop's default value globally to avoid having to specify it for each code block. To do so, add it to the [`defaultProps`](/reference/configuration/#defaultprops) configuration option:

<ConfigVariants
  preferEcConfigFile
  imports={`
    import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections' // no-ins
  `}
  settings={`
    plugins: [pluginCollapsibleSections()], // no-ins
    defaultProps: {
      // Change the default style of collapsible sections
      collapseStyle: 'collapsible-auto',
    },
  `}
/>

In the following sections, you can see the different styles in action.

#### `github` (default style)

This style is similar to the one used by GitHub. A summary line with an expand icon and the default text `X collapsed lines` is shown. When expanded, the summary line is replaced by the section's code lines. It is not possible to re-collapse the section.

<Code lang="js" code={exampleCode} meta={exampleMeta} />

#### `collapsible-start`

When collapsed, the summary line looks like the `github` style. However, when expanded, it remains visible before the expanded code lines, making it possible to re-collapse the section.

<Code lang="js" code={exampleCode} meta={exampleMeta + ' collapseStyle=collapsible-start'} />

#### `collapsible-end`

Same as `collapsible-start`, but the summary line remains visible after the expanded code lines.

<Code lang="js" code={exampleCode} meta={exampleMeta + ' collapseStyle=collapsible-end'} />

#### `collapsible-auto`

Automatically selects `collapsible-start` or `collapsible-end` based on the location of the collapsible section in the code block. Uses `collapsible-start` unless the section ends at the end of the code block, in which case `collapsible-end` is used.

<Code lang="js" code={exampleCode} meta={exampleMeta + ' collapseStyle=collapsible-auto'} />

## Usage in the `<Code>` component

The collapsible sections plugin adds the following props to the `<Code>` component that allow direct access to its features:

### Props

#### collapse

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

Collapses the given line range or ranges.

#### collapsePreserveIndent

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

Determines if the summary line content of collapsible sections should be indented to match the minimum indent level of the contained code lines.

#### collapseStyle

<PropertySignature>
- Type: `"github"` \| `"collapsible-start"` \| `"collapsible-end"` \| `"collapsible-auto"`
- Default: ``'github'``
</PropertySignature>

Allows to select one of the following collapsible section styles:

- `github`: The default style, similar to the one used by GitHub. A summary line with an expand icon and the default text `X collapsed lines` is shown. When expanded, the summary line is replaced by the section's code lines. It is not possible to re-collapse the section.
- `collapsible-start`: When collapsed, the summary line looks like the `github` style. However, when expanded, it remains visible above the expanded code lines, making it possible to re-collapse the section.
- `collapsible-end`: Same as `collapsible-start`, but the summary line remains visible below the expanded code lines.
- `collapsible-auto`: Automatically selects `collapsible-start` or `collapsible-end` based on the location of the collapsible section in the code block. Uses `collapsible-start` unless the section ends at the bottom of the code block, in which case `collapsible-end` is used.

## Styling

This plugin adds a `collapsibleSections` object to the `styleOverrides` engine config option, allowing you to customize the visual appearance of the sections:

<ConfigVariants
  preferEcConfigFile
  imports={`
    import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections' // no-ins
  `}
  settings={`
    plugins: [pluginCollapsibleSections()], // no-ins
    styleOverrides: {
      // You can optionally override the plugin's default styles here
      collapsibleSections: {
        closedBackgroundColor: '#68F',
      },
    },
  `}
/>

### Available style overrides

#### closedBackgroundColor

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ theme }) => setAlpha(theme.colors['editor.foldBackground'], 0.2) || 'rgb(84 174 255 / 20%)'``
</PropertySignature>

The background color of the summary line.

#### closedBorderColor

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ theme }) => setAlpha(theme.colors['editor.foldBackground'], 0.5) || 'rgb(84 174 255 / 50%)'``
</PropertySignature>

The border color of the summary line.

#### closedBorderWidth

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

The border width of the summary line.

Note: Despite the setting prefix `closed`, summary lines are also visible while the section is open when using any of the `collapsible-*` styles. This is the same for all `closed*` settings.

#### closedFontFamily

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

The font family of the section summary line.

#### closedFontSize

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

The font size of the section summary line.

#### closedLineHeight

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

The line height of the section summary line.

#### closedMargin

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

The margin around the summary line.

#### closedPaddingBlock

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

The block padding of the summary line.

#### closedTextColor

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

The text color of the section summary line.

#### collapseIcon

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

An inline SVG URL for the collapse 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).

#### expandIcon

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

An inline SVG URL for the expand 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).

#### openBackgroundColor

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

The background color of expanded code lines when using the default `github` style.

#### openBackgroundColorCollapsible

<PropertySignature>
- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)
- Default: ``({ theme }) => setAlpha(theme.colors['editor.foldBackground'], 0.1) || 'rgb(84 174 255 / 10%)'``
</PropertySignature>

The background color of expanded code lines when using any of the `collapsible-*` styles.

#### openBorderColor

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

The color of the border around expanded code lines.

#### openBorderWidth

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

The width of the border around expanded code lines.

#### openMargin

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

The margin around open sections.

#### openPadding

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

The padding of open sections.
