> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumen.bjanczak.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lumen Editor HTML Sanitizer Configuration Reference

> Configure Lumen Editor's built-in HTML sanitizer: allowed tags, attributes, URL protocols, image data URIs, and CSS style properties.

Every time content enters the editor — whether from the `value` option, a paste event, or programmatic insertion — it passes through a built-in HTML sanitizer. The sanitizer strips any tags, attributes, URL protocols, and CSS properties that are not on the allowlist, helping you prevent cross-site scripting (XSS) attacks without adding a separate library. You can tighten or adjust the allowlist via the `sanitize` constructor option.

<Warning>
  Relaxing the sanitizer — for example, by adding `script` to `tags`, permitting `javascript:` protocols, or allowing unrestricted `style` properties — can reintroduce XSS attack vectors in your application. Only expand the allowlist to the minimum set your use-case genuinely requires.
</Warning>

<Note>
  Attributes matching the pattern `on*=` (e.g. `onclick`, `onmouseover`) are **always stripped** from all elements, regardless of what you specify in `attrs`. This protection cannot be disabled via the `sanitize` option.
</Note>

## Default allowlist

Out of the box, Lumen Editor permits a broad but safe set of HTML constructs. The tables below show what is allowed when you do not supply a custom `sanitize` config.

### Allowed tags

| Tag              | Purpose                             |
| ---------------- | ----------------------------------- |
| `p`              | Paragraph                           |
| `strong`         | Bold (semantic)                     |
| `em`             | Italic (semantic)                   |
| `u`              | Underline                           |
| `s`              | Strikethrough                       |
| `h1`, `h2`, `h3` | Headings                            |
| `ul`, `ol`, `li` | Unordered and ordered lists         |
| `blockquote`     | Block quotation                     |
| `pre`, `code`    | Preformatted text and inline code   |
| `a`              | Hyperlink                           |
| `img`            | Image                               |
| `br`, `hr`       | Line break and horizontal rule      |
| `div`, `span`    | Generic block and inline containers |

### Allowed attributes

| Selector           | Permitted attributes             |
| ------------------ | -------------------------------- |
| `*` (all elements) | `class`, `id`, `style`           |
| `a`                | `href`, `title`, `rel`, `target` |
| `img`              | `src`, `alt`, `width`, `height`  |

### Allowed URL protocols

These protocols are permitted in `href` and non-image `src` attributes:

| Protocol |
| -------- |
| `http:`  |
| `https:` |

### Allowed image source protocols

These protocols are permitted in `img[src]` attributes:

| Protocol                 |
| ------------------------ |
| `https:`                 |
| `data:image/png;base64`  |
| `data:image/jpeg;base64` |
| `data:image/gif;base64`  |
| `data:image/webp;base64` |

### Allowed CSS style properties

The following properties are permitted inside `style` attributes. The sanitizer also blocks `url()`, `expression()`, and `@import` constructs inside any style value, regardless of the property allowlist.

| Property           |
| ------------------ |
| `color`            |
| `background-color` |
| `font-size`        |
| `font-weight`      |
| `font-style`       |
| `text-align`       |
| `text-decoration`  |
| `margin`           |
| `padding`          |

## The `sanitize` option

Pass a `sanitize` object as a constructor option to override the defaults. When you provide this object it **replaces** the default config entirely — any key you omit defaults to an empty or disabled value rather than inheriting the built-in default. Specify every key you need.

<ParamField body="tags" type="string[]">
  An explicit allowlist of HTML tag names. Any tag not in this array is stripped (its child nodes are preserved where safe). Tag names are case-insensitive.

  ```js theme={null}
  tags: ['p', 'strong', 'em', 'a', 'code', 'pre']
  ```
</ParamField>

<ParamField body="attrs" type="Record<string, string[]>">
  A map from element selector to an array of permitted attribute names. Use the key `'*'` to apply an attribute allowlist to every element. Per-element keys (e.g. `'a'`, `'img'`) apply in addition to the `'*'` list.

  ```js theme={null}
  attrs: {
    '*': ['class'],
    a: ['href', 'title', 'rel', 'target'],
    img: ['src', 'alt', 'width', 'height']
  }
  ```
</ParamField>

<ParamField body="protocols" type="string[]">
  URL protocols permitted in `href` and non-image `src` attributes. Values must include the trailing colon (e.g. `'https:'`). Any link whose URL scheme is not in this list has its attribute removed.

  ```js theme={null}
  protocols: ['https:']
  ```
</ParamField>

<ParamField body="imgProtocols" type="string[]">
  URL protocols permitted specifically in `img[src]` attributes. Use this in combination with `dataImages` to control whether data URIs are allowed for images independently of other URL protocols.

  ```js theme={null}
  imgProtocols: ['https:']
  ```
</ParamField>

<ParamField body="dataImages" type="boolean">
  When `true`, data URI image sources (`data:image/*;base64,...`) are permitted in `img[src]`, in addition to any entries in `imgProtocols`. When `false`, data URI images are stripped even if a `data:` scheme appears in `imgProtocols`. Defaults to `false` in a fully custom config.

  ```js theme={null}
  dataImages: false
  ```
</ParamField>

<ParamField body="styles" type="string[]">
  An allowlist of CSS property names that may appear in `style` attributes. Any CSS property not in this array is removed from the style value. Pass an empty array (`[]`) to strip all inline styles.

  ```js theme={null}
  styles: ['color', 'font-weight', 'text-align']
  ```
</ParamField>

## Hardening example

For applications where users should only be able to produce minimal formatted text — with no images, no heading tags, no inline styles, and only HTTPS links — you can lock the sanitizer down to a strict subset:

```js theme={null}
new Editor('#editor', {
  sanitize: {
    tags: ['p', 'strong', 'em', 'a', 'code', 'pre'],
    attrs: {
      '*': ['class'],
      a: ['href', 'title', 'rel', 'target']
    },
    protocols: ['https:'],
    imgProtocols: ['https:'],
    dataImages: false,
    styles: []
  }
});
```

This configuration:

* Limits content to six tags — paragraphs, bold, italic, links, inline code, and code blocks.
* Permits only the `class` attribute on all elements, plus `href`, `title`, `rel`, and `target` on `<a>` tags.
* Allows only `https:` link targets, blocking `http:`, `ftp:`, `javascript:`, and all other schemes.
* Disables all data-URI images.
* Strips all inline CSS from every element.

<Tip>
  Setting `styles: []` is the simplest way to prevent users from smuggling arbitrary CSS (such as `position: fixed` overlays or invisible text) into your page.
</Tip>