Word Wrap

When your code blocks contain long lines, it can be helpful to enable word wrap to keep the code within the bounds of the container and avoid the need for horizontal scrolling.

No installation required

This feature is provided by the Expressive Code core package. You can start using it right away in your documents!

Usage in markdown / MDX

Configuring word wrap per block

You can enable or disable word wrap on individual code blocks using the wrap boolean prop in the meta information of your code blocks. This is done by appending wrap or wrap=true to your opening code fence to enable word wrapping, or wrap=false to disable it:

```js wrap
// Example with wrap
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}
```

```js wrap=false
// Example with wrap=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}
```

The above code will be rendered like this:

// Example with wrap
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

// Example with wrap=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

Note

Manually adding the wrap prop as shown above is useful if you only want to change the behavior of a few code blocks on your site. If you want to affect all code blocks, you can do so in the configuration instead.

Configuring indentation of wrapped lines

Indent preservation

By default, 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.

You can disable the default behavior so that wrapped parts of lines will always start at column 1. This can be useful to reproduce terminal output.

To configure this behavior, you can use the preserveIndent boolean prop in the meta information of your code blocks:

```js wrap preserveIndent
// Example with preserveIndent (enabled by default)
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}
```

```js wrap preserveIndent=false
// Example with preserveIndent=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}
```

The above code will be rendered like this:

// Example with preserveIndent (enabled by default)
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

// Example with preserveIndent=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

Hanging indent

You can also define a number of columns by which all wrapped lines should be indented.

If preserveIndent is true (which is the default), this value will be added to the indentation of the original line. Otherwise, the indentation of any wrapped lines will be fixed to the specified number of columns.

To configure this behavior, you can use the hangingIndent numeric prop in the meta information of your code blocks:

```js wrap hangingIndent=2
// Example with hangingIndent=2
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}
function heavilyIndentedCode() {
          return 'This long line already starts with a lot of indentation, and its wrapped parts will be indented by 2 additional columns due to hangingIndent=2'
}
```

```js wrap hangingIndent=2 preserveIndent=false
// Example with hangingIndent=2 and preserveIndent=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}
function heavilyIndentedCode() {
          return 'Even though this long line starts with a lot of indentation, its wrapped parts will only be indented by 2 columns due to the combination of hangingIndent=2 and preserveIndent=false'
}
```

The above code will be rendered like this:

// Example with hangingIndent=2
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}
function heavilyIndentedCode() {
          return 'This long line already starts with a lot of indentation, and its wrapped parts will be indented by 2 additional columns due to hangingIndent=2'
}

// Example with hangingIndent=2 and preserveIndent=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}
function heavilyIndentedCode() {
          return 'Even though this long line starts with a lot of indentation, its wrapped parts will only be indented by 2 columns due to the combination of hangingIndent=2 and preserveIndent=false'
}

Usage in the <Code> component

The following props are available on the <Code> component to configure word wrap behavior:

Props

wrap

Type: boolean Default: false

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.

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.

preserveIndent

Type: boolean Default: true

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

Type: number Default: 0

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.

Configuration

You can configure the default word wrap settings using the defaultProps option in your Expressive Code configuration. You can also change the defaults by language using the sub-property overridesByLang:

Astro

astro.config.mjs

import { defineConfig } from 'astro/config'
import astroExpressiveCode from 'astro-expressive-code'

export default defineConfig({
  integrations: [
    astroExpressiveCode({
      defaultProps: {
        // Enable word wrap by default
        wrap: true,
        // Disable wrapped line indentation for terminal languages
        overridesByLang: {
          'bash,ps,sh': { preserveIndent: false },
        },
      },
    }),
  ],
})

Starlight

astro.config.mjs

import { defineConfig } from 'astro/config'
import starlight from '@astrojs/starlight'

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Starlight site',
      expressiveCode: {
        defaultProps: {
          // Enable word wrap by default
          wrap: true,
          // Disable wrapped line indentation for terminal languages
          overridesByLang: {
            'bash,ps,sh': { preserveIndent: false },
          },
        },
      },
    }),
  ],
})

Next.js

next.config.mjs

import createMDX from '@next/mdx'
import rehypeExpressiveCode from 'rehype-expressive-code'

/** @type {import('rehype-expressive-code').RehypeExpressiveCodeOptions} */
const rehypeExpressiveCodeOptions = {
  defaultProps: {
    // Enable word wrap by default
    wrap: true,
    // Disable wrapped line indentation for terminal languages
    overridesByLang: {
      'bash,ps,sh': { preserveIndent: false },
    },
  },
}

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  pageExtensions: ["js", "jsx", "ts", "tsx", "md", "mdx"],
}

const withMDX = createMDX({
  extension: /\.mdx?$/,
  options: {
    remarkPlugins: [],
    rehypePlugins: [
      // The nested array structure is required to pass options
      // to a rehype plugin
      [rehypeExpressiveCode, rehypeExpressiveCodeOptions],
    ],
  },
})

export default withMDX(nextConfig)