---
title: Word Wrap
---

import ConfigVariants from '@components/ConfigVariants.astro'
import PropertySignature from '@components/PropertySignature.astro'

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.

:::tip[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:

````md ins=/(?\<=&#96;.*)wrap\S*/
```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:

```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'
}
```

:::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](#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:

````md ins=/(?\<=&#96;.*)preserveIndent\S*/
```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:

```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'
}
```

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

````md ins=/(?\<=&#96;.*)hangingIndent\S*/
```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:

```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'
}
```

## Usage in the `<Code>` component

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

### Props

#### wrap

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

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

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

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

<PropertySignature>
- Type: `number`
- Default: ``0``
</PropertySignature>

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`:

<ConfigVariants
  settings={`
    defaultProps: {
      // Enable word wrap by default
      wrap: true,
      // Disable wrapped line indentation for terminal languages
      overridesByLang: {
        'bash,ps,sh': { preserveIndent: false },
      },
    },
  `}
/>
