> ## 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 Constructor Options: Complete Reference

> Complete reference for all Lumen Editor constructor options, including types, defaults, and descriptions for every supported configuration key.

You pass options as the second argument to the `Editor` constructor. Every option is optional — you only need to provide the ones that differ from the defaults. The first argument is a CSS selector string (or a DOM element reference) identifying the container element where Lumen Editor will mount.

```js theme={null}
const editor = new Editor('#editor', {
  placeholder: 'Write here…',
  theme: 'light',
  locale: 'en',
  value: '<p>Hello world</p>',
  toolbar: [
    ['undo', 'redo'],
    ['h1', 'h2', 'paragraph'],
    ['bold', 'italic', 'underline'],
    ['ul', 'ol'],
    ['link', 'image', 'code'],
    ['html']
  ],
  autoSave: { key: 'my-doc', debounce: 800 },
  uploadImage: async (file) => '/uploads/my-image.png',
  plugins: [plugin1, plugin2],
  modules: [...Object.values(modules), customModule],
  sanitize: {
    tags: ['p', 'strong', 'em', 'a', 'code', 'pre'],
    attrs: { '*': ['class'], a: ['href', 'title', 'rel', 'target'] },
    protocols: ['https:'],
    imgProtocols: ['https:'],
    dataImages: false,
    styles: []
  },
  maxImageSize: 5 * 1024 * 1024,
  allowedImageTypes: ['image/png', 'image/jpeg', 'image/gif', 'image/webp']
});
```

## Options reference

<ParamField body="placeholder" type="string" optional>
  Ghost text displayed inside the editor when its content is empty. Accepts any plain string. Defaults to an empty string (no placeholder shown).
</ParamField>

<ParamField body="theme" type="&#x22;light&#x22; | &#x22;dark&#x22;" optional>
  Visual theme applied to the editor UI. Set to `'dark'` to activate the built-in dark colour scheme. Defaults to `'light'`.

  ```js theme={null}
  theme: 'dark'
  ```
</ParamField>

<ParamField body="locale" type="string | object" optional>
  Controls the language used for toolbar tooltips and ARIA labels. Pass `'en'` or `'tr'` to use a built-in locale, or supply a custom locale object to provide your own strings. Defaults to `'en'`.

  ```js theme={null}
  // Built-in locale
  locale: 'tr'

  // Custom locale object
  locale: {
    bold: 'Bold',
    italic: 'Italic',
    // ... all other keys
  }
  ```
</ParamField>

<ParamField body="value" type="string" optional>
  Initial HTML content loaded into the editor on mount. The string is passed through the sanitizer before rendering. Defaults to an empty string.

  ```js theme={null}
  value: '<p>Hello <strong>world</strong></p>'
  ```
</ParamField>

<ParamField body="toolbar" type="string[][]" optional>
  Defines which command buttons appear in the toolbar and how they are grouped. Each inner array is a group of command names separated by a visual divider. Omit a group or command name to hide those controls entirely.

  ```js theme={null}
  toolbar: [
    ['undo', 'redo'],
    ['h1', 'h2', 'paragraph'],
    ['bold', 'italic', 'underline'],
    ['ul', 'ol'],
    ['link', 'image', 'code'],
    ['html']
  ]
  ```

  See the [Modules reference](./modules) for the full list of built-in command names.
</ParamField>

<ParamField body="autoSave" type="{ key: string, debounce: number }" optional>
  Enables automatic persistence of editor content to `localStorage`. `key` is the storage key under which the HTML is saved. `debounce` is the delay in milliseconds after the last keystroke before the save fires. When present, the stored value is restored on next mount (taking precedence over `value`).

  ```js theme={null}
  autoSave: { key: 'my-doc', debounce: 800 }
  ```
</ParamField>

<ParamField body="uploadImage" type="async (file: File) => string" optional>
  An async function called when the user selects an image through the image toolbar button. Receive the raw `File` object, upload it however you like, and return the public URL string that will be inserted into the editor as the `src` of an `<img>` tag.

  ```js theme={null}
  uploadImage: async (file) => {
    const form = new FormData();
    form.append('image', file);
    const res = await fetch('/api/upload', { method: 'POST', body: form });
    const { url } = await res.json();
    return url;
  }
  ```

  <Tip>
    Combine `uploadImage` with `maxImageSize` and `allowedImageTypes` to validate files before they are uploaded.
  </Tip>
</ParamField>

<ParamField body="plugins" type="((editor: Editor) => void)[]" optional>
  An array of plugin functions, each of which receives the `Editor` instance and can extend or modify its behaviour. Plugins are called once, in order, immediately after the editor has mounted.

  ```js theme={null}
  function myPlugin(editor) {
    // attach custom event listeners, override methods, etc.
  }

  plugins: [myPlugin]
  ```
</ParamField>

<ParamField body="modules" type="EditorModule[]" optional>
  The full set of toolbar module definitions available to the editor. Defaults to the complete built-in modules set. Pass a merged array to add custom modules alongside the defaults, or a completely custom array to replace the built-in set entirely.

  ```js theme={null}
  import { Editor, modules } from 'lumen-editor';

  new Editor('#editor', {
    modules: [...Object.values(modules), customModule]
  });
  ```

  See the [Modules reference](./modules) for the module object shape and a list of all built-in modules.
</ParamField>

<ParamField body="sanitize" type="object" optional>
  A configuration object that overrides the default HTML sanitizer allowlist. When provided, it entirely replaces the defaults — any key you omit falls back to an empty/disabled state rather than inheriting the default. Supply all required keys explicitly.

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

  See the [Sanitizer reference](./sanitizer) for a full breakdown of each key and a hardening example.
</ParamField>

<ParamField body="maxImageSize" type="number" optional>
  Maximum permitted file size (in bytes) for images inserted via the toolbar image button. Files that exceed this limit are rejected before `uploadImage` is called. Defaults to `5242880` (5 MB).

  ```js theme={null}
  maxImageSize: 2 * 1024 * 1024  // 2 MB
  ```
</ParamField>

<ParamField body="allowedImageTypes" type="string[]" optional>
  An allowlist of MIME types for images inserted via the toolbar. Files whose type is not in this list are rejected before `uploadImage` is called. Defaults to `['image/png', 'image/jpeg', 'image/gif', 'image/webp']`.

  ```js theme={null}
  allowedImageTypes: ['image/png', 'image/jpeg']
  ```
</ParamField>

## Full example

The snippet below shows all options used together for reference. In practice, only include the options you need to override.

```js theme={null}
import { Editor, modules } from 'lumen-editor';

const editor = new Editor('#editor', {
  placeholder: 'Write here…',
  theme: 'light',
  locale: 'en',
  value: '<p>Hello world</p>',
  toolbar: [
    ['undo', 'redo'],
    ['h1', 'h2', 'paragraph'],
    ['bold', 'italic', 'underline'],
    ['ul', 'ol'],
    ['link', 'image', 'code'],
    ['html']
  ],
  autoSave: { key: 'my-doc', debounce: 800 },
  uploadImage: async (file) => {
    const form = new FormData();
    form.append('image', file);
    const res = await fetch('/api/upload', { method: 'POST', body: form });
    const { url } = await res.json();
    return url;
  },
  plugins: [plugin1, plugin2],
  modules: [...Object.values(modules), customModule],
  sanitize: {
    tags: ['p', 'strong', 'em', 'a', 'code', 'pre'],
    attrs: { '*': ['class'], a: ['href', 'title', 'rel', 'target'] },
    protocols: ['https:'],
    imgProtocols: ['https:'],
    dataImages: false,
    styles: []
  },
  maxImageSize: 5 * 1024 * 1024,
  allowedImageTypes: ['image/png', 'image/jpeg', 'image/gif', 'image/webp']
});
```

## Related pages

<CardGroup cols={3}>
  <Card title="Sanitizer" icon="shield-halved" href="./sanitizer">
    Customise the HTML allowlist to control which tags, attributes, and CSS properties survive sanitisation.
  </Card>

  <Card title="Modules" icon="puzzle-piece" href="./modules">
    Explore all 17 built-in toolbar modules and learn how to define your own.
  </Card>

  <Card title="Custom Toolbar" icon="bars" href="../guides/custom-toolbar">
    Step-by-step guide to building and registering a custom toolbar module.
  </Card>
</CardGroup>