Configuration
EditorConfig and RendererConfig are the entry points for every customisation. Pass either to Editor.create() or Renderer.render() respectively. Only containerId (and data for the renderer) are required; all other options have safe defaults.
EditorConfig
Pass EditorConfig as the sole argument to Editor.create(). The required containerId must match an existing DOM element id.
| Option | Type | Required | Description |
|---|---|---|---|
| containerId | string | Yes | ID of the DOM element that will host the editor. Must exist in the DOM before Editor.create() is called. |
| maxHeight | number | No | Maximum height of the editor in pixels. Set to 0 (the default) for no height limit. |
| minHeight | number | No | Minimum height of the editor in pixels. Defaults to 300. |
| onChange | (data: EditorData) => void | No | Callback fired whenever the document changes. Receives the full EditorData snapshot. |
| onReady | () => void | No | Callback fired once the editor is fully initialised and ready to accept API calls. |
| placeholder | string | No | Placeholder text shown when the editor is empty. Defaults to 'Start writing...'. |
| initialData | EditorData | No | Pre-populated EditorData to load when the editor mounts. |
| initialView | 'edit' | 'preview' | 'json' | No | Starting view mode. One of: edit, preview, json. Defaults to 'edit'. |
| allowJsonViewEditing | boolean | No | When true, the JSON view is editable and changes propagate back into the document. Defaults to false. |
| margins | BlockMargins | No | Global top and bottom margin (in pixels) applied to every block. Per-block configs take precedence. |
| styles | EditorStyles | No | EditorStyles object for fine-grained CSS customisation of editor chrome (toolbars, dialogs, controls). |
| classNames | EditorClassNames | No | EditorClassNames object to attach CSS class names to editor chrome elements. |
| imageUploader | UploadFunction | No | Async function that uploads an image file and returns a public URL string. |
| audioUploader | UploadFunction | No | Async function that uploads an audio file and returns a public URL string. |
| videoUploader | UploadFunction | No | Async function that uploads a video file and returns a public URL string. |
| theme | 'auto' | 'light' | 'dark' | No | Colour scheme. One of: auto (follows system), light, dark. Defaults to auto. |
| themeOverrides | { light?: ThemeTokens; dark?: ThemeTokens } | No | Per-mode token overrides. Supply light and/or dark token maps to customise colours without replacing the full theme. |
TypeScript
import { Editor } from '@clepit/core';
const editor = Editor.create({
containerId: 'editor',
minHeight: 400,
placeholder: 'Start writing...',
theme: 'auto',
onChange: data => console.log(data),
onReady: () => console.log('Editor ready'),
imageUploader: async file => {
const form = new FormData();
form.append('file', file);
const res = await fetch('/api/upload', { body: form, method: 'POST' });
const { url } = await res.json();
return url;
},
});RendererConfig
Pass RendererConfig as the sole argument to Renderer.render(). Both containerId and data are required.
| Option | Type | Required | Description |
|---|---|---|---|
| containerId | string | Yes | ID of the DOM element where the rendered output will be injected. |
| data | EditorData | Yes | The EditorData document to render. Required. |
| margins | BlockMargins | No | Global top and bottom margin (in pixels) applied to every rendered block. |
| styles | BlockStyles | No | BlockStyles map for per-block-type CSS customisation of rendered output. |
| classNames | BlockClassNames | No | BlockClassNames map for per-block-type CSS class names on rendered output. |
| editorClassNames | EditorClassNames | No | EditorClassNames passed through to blocks that render interactive components (e.g. tooltip classNames for paragraphs). |
| configs | Partial<BlockTypeOutputConfigs> | No | Partial map of per-block OutputConfig objects. Each entry can set block-level margins and tooltip class names. |
| theme | 'auto' | 'light' | 'dark' | No | Colour scheme. One of: auto, light, dark. |
| themeOverrides | { light?: ThemeTokens; dark?: ThemeTokens } | No | Per-mode token overrides for the rendered output. |
TypeScript
import { Renderer } from '@clepit/core';
import type { EditorData } from '@clepit/core';
const data: EditorData = await fetch('/api/content/123').then(r => r.json());
Renderer.render({
containerId: 'output',
data,
theme: 'auto',
margins: { bottom: 16, top: 16 },
});Block-level styling
Both EditorConfig and RendererConfig accept styles, classNames, and configs keyed by block type. Use these for targeted overrides; see the Themes page for the complete per-token reference.
TypeScript
import { Editor, Renderer } from '@clepit/core';
import type { BlockStyles, BlockClassNames, EditorStyles } from '@clepit/core';
const editorStyles: EditorStyles = {
blockToolbar: { container: { borderRadius: '8px' } },
};
const blockStyles: BlockStyles = {
header: { h1: { fontFamily: 'Georgia, serif' } },
paragraph: { lineHeight: '1.75' },
table: { cell: { padding: '8px 12px' } },
};
const blockClassNames: BlockClassNames = {
paragraph: 'prose-paragraph',
header: { h1: 'prose-h1', h2: 'prose-h2' },
alert: { info: 'alert-info', error: 'alert-error' },
};
Editor.create({
containerId: 'editor',
styles: editorStyles,
});
Renderer.render({
containerId: 'output',
data,
styles: blockStyles,
classNames: blockClassNames,
});