Menu ▾ ▴

Configuration

neikiri

⚙️ Configuration

All configuration options for Neiki's Editor, with types, defaults, and examples.

📋 Basic Usage

const editor = new NeikiEditor('#editor', {
    // options here
});

[!NOTE]
All options are optional. The editor works with zero configuration out of the box.

📊 Options Reference

Option Type Default Description
placeholder string 'Start typing...' Ghost text shown when the editor is empty
minHeight number 300 Minimum editor height in pixels
maxHeight number\|null null Maximum height in pixels; enables scroll when exceeded. When null, the toolbar uses position: sticky.
autofocus boolean false Automatically focus the editor on initialization
spellcheck boolean true Enable browser spellcheck
readonly boolean false Make editor read-only (visible but not editable)
theme string 'light' Initial theme: 'light', 'dark', 'blue', 'dark-blue'
language string 'en' UI language: en, cs, zh, es, de, fr, pt, ja
autosaveKey string\|null null Custom localStorage scope for autosave isolation
toolbar array (default set) Array of toolbar button identifiers
customClass string\|null null Extra CSS class appended to the content area
showHelp boolean true Show Help button in the More menu (⋯)
imageUploadHandler function\|null null Async (file) => Promise<url> for server image uploads
videoUploadHandler function\|null null Async (file) => Promise<url> for server video uploads
translations object {} Custom/override translation strings
onChange function\|null null Callback fired on every content change
onSave function\|null null Callback fired on save (Ctrl+S or More → Save)
onFocus function\|null null Callback fired when editor gains focus
onBlur function\|null null Callback fired when editor loses focus
onReady function\|null null Callback fired once the editor is fully initialized

🔧 Option Details

placeholder

Shown as ghost text when the editor is empty. Disappears when the user starts typing.

new NeikiEditor('#editor', {
    placeholder: 'Write your article here...'
});

minHeight / maxHeight

Control the vertical size of the editor:

new NeikiEditor('#editor', {
    minHeight: 200,
    maxHeight: 600    // content scrolls after 600px
});

[!TIP]
With maxHeight: null (default), the editor grows with content and the toolbar becomes sticky — it stays visible while the user scrolls through long documents.

theme

Set the initial color theme. The user can change themes at runtime via the More menu.

new NeikiEditor('#editor', {
    theme: 'dark'   // 'light' | 'dark' | 'blue' | 'dark-blue'
});

[!IMPORTANT]
If the user has previously toggled the theme, the persisted localStorage value overrides this config option. User preference is always respected. See Themes & Styling for details.

language

Set the UI language. Affects all tooltips, modals, status bar text, and system messages.

new NeikiEditor('#editor', {
    language: 'cs'   // Czech UI
});

Available languages:

Code Language
en English (default)
cs Czech
zh Chinese
es Spanish
de German
fr French
pt Portuguese
ja Japanese

[!NOTE]
Language must be set at initialization. Changing it at runtime requires re-initializing the editor.

autosaveKey

By default, autosave is scoped to the page URL + editor identity. When your app edits different records at the same URL, use autosaveKey to isolate drafts:

new NeikiEditor('#editor', {
    autosaveKey: 'article-42'
});

See Advanced Features — Autosave for full details.

customClass

Appends an extra CSS class to the content area alongside the default neiki-content class:

new NeikiEditor('#editor', {
    customClass: 'my-custom-content'
});

Renders as:

<div class="neiki-content my-custom-content" contenteditable="true"></div>

Use it to apply custom typography without touching the default styles:

.my-custom-content {
    font-family: 'Georgia', serif;
    font-size: 18px;
    line-height: 1.8;
}

[!NOTE]
The old name custom_class is still accepted for backward compatibility.

imageUploadHandler

An async callback for uploading images to your server instead of embedding them as base64. Applies to file picker, drag & drop, and clipboard paste.

new NeikiEditor('#editor', {
    imageUploadHandler: async (file) => {
        const formData = new FormData();
        formData.append('image', file);
        const res = await fetch('/api/upload', { method: 'POST', body: formData });
        const data = await res.json();
        return data.url;  // must return the final image URL
    }
});

[!TIP]
Using imageUploadHandler is strongly recommended for production. It prevents bloated base64 content and lets browsers cache images properly.

videoUploadHandler

Same as imageUploadHandler but for videos. Without it, video files are embedded as base64.

new NeikiEditor('#editor', {
    videoUploadHandler: async (file) => {
        const formData = new FormData();
        formData.append('video', file);
        const response = await fetch('/api/upload-video', { method: 'POST', body: formData });
        const data = await response.json();
        return data.url;
    }
});

translations

Override or extend any built-in translation string. Keys you provide are merged with the built-in ones — you only need to supply what you want to change.

new NeikiEditor('#editor', {
    language: 'en',
    translations: {
        'toolbar.bold': 'Make it bold',
        'placeholder': 'Start your story...'
    }
});

Callbacks

All callbacks receive the editor instance or relevant data:

new NeikiEditor('#editor', {
    onReady: function(editor) {
        console.log('Editor ready!', editor);
    },

    onChange: function(content) {
        // fires on every keystroke / change
        console.log('New content:', content);
    },

    onSave: function(content) {
        // fires on Ctrl+S or More → Save
        fetch('/api/save', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ content })
        });
    },

    onFocus: function() {
        document.title = '✏️ Editing...';
    },

    onBlur: function() {
        document.title = 'My Page';
    }
});

🏗️ Toolbar Configuration

Customize the toolbar by passing an array of button identifiers:

new NeikiEditor('#editor', {
    toolbar: [
        'bold', 'italic', 'underline', '|',
        'heading', 'fontSize', '|',
        'bulletList', 'numberedList', '|',
        'insertDropdown', '|',
        'moreMenu'
    ]
});
  • Use '|' as a separator between groups. Groups wrap as whole units on narrow screens.
  • Plugin buttons are referenced by their registered name.

For the full list of available buttons, see the Toolbar Reference.

Default toolbar (all features):

toolbar: [
    'viewCode', 'undo', 'redo', 'findReplace', '|',
    'bold', 'italic', 'underline', 'strikethrough', 'superscript', 'subscript', 'code', 'removeFormat', '|',
    'heading', 'fontFamily', 'fontSize', '|',
    'foreColor', 'backColor', '|',
    'alignLeft', 'alignCenter', 'alignRight', 'alignJustify', '|',
    'indent', 'outdent', '|',
    'bulletList', 'numberedList', 'blockquote', 'horizontalRule', '|',
    'insertDropdown', '|',
    'moreMenu'
]
🔧 Toolbar Reference All available toolbar button identifiers
🔌 Plugin API Add custom buttons via plugins
🧩 Advanced Features Autosave, themes, i18n deep dives
🎨 Themes & Styling CSS customization guide

Related

Wiki: API Reference