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

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 also disable this behavior so that wrapped parts of long lines will always start at column 1. This can be useful to reproduce terminal output.

To change this behavior for a code block, 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'
}

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.

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)