unilexical

UniLexical

Framework-agnostic, Notion-style block editor
Powered by Lexical · Pure TypeScript core · Thin Vue 3 / React / Vanilla wrappers

📚 Documentation · 🤖 LLMs.txt · Features · Install · Quick start · Config · Toolbar · Preview · API · Events

UniLexical is an industrial-grade, block-based rich-text editor. The editor state, plugins, toolbar, slash menu, drag handles, and serialization live in a framework-agnostic TypeScript core. Vue 3 and React are thin lifecycle wrappers only—so you get one consistent behavior across stacks.

Features

• Block model – Every top-level unit is a block with hover chrome (drag + plus)
• Drag & drop reorder – Notion-like handle; click handle for a block more-menu (delete / turn into / color / …)
• Plus button – Empty line → open / without adding a line; non-empty → insert below + slash
• Slash menu – Type / for headings, lists, todo, table, image, divider, code, …
• Markdown shortcuts – # , > , - , 1. , **bold**, *italic*, `code`, …
• Configurable toolbar – Full set by default; pass toolbarItems for a strict subset
• Import / export – HTML · Markdown · JSON
• Images – Custom upload or default base64; paste / drop screenshots supported
• Attachments – Optional custom upload
• Tables – Interactive grid size picker (default 5×5, configurable)
• Checklists / todo – Visible checkboxes, gutter toggle
• Container / callout – Enter on empty line exits the container
• Live preview – Host-safe content renderer (no chrome styles on your container)
• Material icons – Local outlined SVG toolbar icons

Installation

Package name on npm: unilexical (display name UniLexical).

# Core (Vanilla / any framework)
npm install unilexical

# With Vue 3
npm install unilexical vue

# With React
npm install unilexical react react-dom

Yarn / pnpm:

yarn add unilexical
pnpm add unilexical

Lexical packages are bundled as dependencies of unilexical. You typically do not need to install lexical separately unless you extend nodes yourself.

Styles

// Editor UI (toolbar, slash, drag overlay, tippy)
import 'unilexical/style.css';

// Optional: content-only preview (does not style your host container)
import 'unilexical/preview.css';

Quick start

Vanilla JS / TypeScript

import { mountEditor, mountPreview } from 'unilexical';
import 'unilexical/style.css';
import 'unilexical/preview.css';

const { editor, getHtml, getMarkdown, setContent, destroy } = mountEditor({
  container: '#editor',
  placeholder: "Type '/' for commands…",
  // omit toolbarItems → full toolbar
  toolbarItems: ['bold', 'italic', 'underline', 'divider', 'heading', 'image', 'table'],
  imageOptions: {
    // omit upload → images stored as base64 data URLs
    upload: async (file) => {
      const form = new FormData();
      form.append('file', file);
      const res = await fetch('/api/upload', { method: 'POST', body: form });
      const data = await res.json();
      return data.url; // public URL string
    },
    accept: 'image/*',
    maxSize: 5 * 1024 * 1024, // 5MB
  },
  initialContent: '# Hello UniLexical\n\nStart writing…',
  initialFormat: 'markdown',
});

// Live preview
const preview = mountPreview('#preview');
preview.bindEditor(editor);

editor.on('change', ({ html, markdown, json }) => {
  console.log('changed', { html, markdown, json });
});

// Cleanup
// destroy();
// preview.destroy();

<div id="editor"></div>
<div id="preview"></div>

Vue 3

<script setup lang="ts">
import { ref } from 'vue';
import { UniLexical, UniLexicalPreview } from 'unilexical/vue';
import type { UniEditor } from 'unilexical';
import 'unilexical/style.css';
import 'unilexical/preview.css';

const html = ref('');
const editor = ref<UniEditor | null>(null);

async function uploadImage(file: File): Promise<string> {
  const fd = new FormData();
  fd.append('file', file);
  const res = await fetch('/api/upload', { method: 'POST', body: fd });
  const data = await res.json();
  return data.url;
}
</script>

<template>
  <UniLexical
    :toolbar-items="['bold', 'italic', 'underline', 'divider', 'heading1', 'image', 'table']"
    :image-options="{ upload: uploadImage, maxSize: 5 * 1024 * 1024 }"
    placeholder="Vue 3…"
    initial-content="# Vue + UniLexical"
    initial-format="markdown"
    @change="(p) => (html = p.html)"
    @ready="(ed) => (editor = ed)"
  />
  <UniLexicalPreview :html="html" />
</template>

React

import { useState } from 'react';
import { UniLexical, UniLexicalPreview } from 'unilexical/react';
import 'unilexical/style.css';
import 'unilexical/preview.css';

export function App() {
  const [html, setHtml] = useState('');

  return (
    <>
      <UniLexical
        toolbarItems={['bold', 'italic', 'underline', 'divider', 'heading1', 'image']}
        imageOptions={{
          upload: async (file) => {
            const fd = new FormData();
            fd.append('file', file);
            const res = await fetch('/api/upload', { method: 'POST', body: fd });
            const data = await res.json();
            return data.url as string;
          },
        }}
        placeholder="React…"
        initialContent="# React + UniLexical"
        initialFormat="markdown"
        onChange={({ html }) => setHtml(html)}
        onReady={(editor) => setHtml(editor.getHtml())}
      />
      <UniLexicalPreview html={html} />
    </>
  );
}

Configuration

All of the following are accepted by:

• mountEditor({ ... }) / createUniEditor({ ... }) (Vanilla)
• <UniLexical /> props (Vue / React)
• useLexical({ ... }) (Vue / React hooks)

UniEditorConfig

ImageOptions

imageOptions: {
  upload: async (file) => {
    // 1) upload to your CDN / OSS
    // 2) return the final HTTPS URL
    return 'https://cdn.example.com/a.png';
  },
  accept: 'image/png,image/jpeg,image/webp,image/gif',
  maxSize: 8 * 1024 * 1024,
}

Paste / drop: Ctrl/Cmd+V screenshots and image files, and drag-drop images, use the same pipeline (upload or base64).

AttachmentOptions

Toolbar items

Behavior

• toolbarItems not passed → full feature toolbar (DEFAULT_TOOLBAR_ITEMS).
• toolbarItems: [...] → only the listed controls (order preserved).
• toolbarItems: [] → no toolbar buttons (chrome may still reserve space if builtinUI is true).

Separators:

Full list

Example presets

// Minimal writing
toolbarItems: ['bold', 'italic', 'underline', 'divider', 'link']

// Docs / Notion-like
toolbarItems: [
  'undo', 'redo', 'divider',
  'heading', 'bold', 'italic', 'strike', 'code', 'fontColor', 'divider',
  'bulletList', 'orderedList', 'todo', 'quote', 'codeBlock', 'divider',
  'image', 'table', 'hr',
]

// Separators only control layout between buttons
toolbarItems: ['bold', 'divider', 'image']

Preview

Use UniPreview / UniLexicalPreview to render cleaned HTML outside the editor.

• The host element is not given chrome styles (safe for your design system).
• Content is rendered inside an inner .uni-preview node; import unilexical/preview.css for typography, lists, images, tables, etc.

Vanilla

import { mountPreview } from 'unilexical';
import 'unilexical/preview.css';

const preview = mountPreview('#preview');
preview.bindEditor(editor);     // live
// preview.setHtml(editor.getHtml());
// preview.destroy();

Vue / React

<UniLexicalPreview :html="html" />
<!-- or live instance -->
<UniLexicalPreview :editor="editor" />

<UniLexicalPreview html={html} />
<UniLexicalPreview editor={editor} />

Framework wrappers

Vue 3 – <UniLexical />

Events: change, ready, toolbarChange

Exposed methods (template ref):

React – <UniLexical />

Same options as camelCase props: toolbarItems, imageOptions, initialContent, initialFormat, placeholder, builtinUI, editable, slashItems, className, style.

Callbacks: onChange, onReady, onToolbarChange

Ref handle: getHtml, getMarkdown, getContent, setContent, focus, editor

Hooks

// Vue
import { useLexical } from 'unilexical/vue';

// React
import { useLexical } from 'unilexical/react';

Returns container ref, editor instance, toolbar state, and content helpers for fully custom layouts (builtinUI: false).

API – UniEditor

import { createUniEditor, type UniEditor } from 'unilexical';

const editor = createUniEditor(config);
editor.mount(element);

Content

UI / state

Events

const off = editor.on('change', ({ html, markdown, json }) => { /* ... */ });
off(); // unsubscribe

Block UX

Markdown shortcuts (selection)

Import & export

editor.getHtml();
editor.getMarkdown();
editor.getJson();

editor.setContent(html, 'html');
editor.setContent(md, 'markdown');
editor.setContent(json, 'json');

HTML export strips structural block wrappers for clean publishing markup while keeping semantic tags / theme classes where applicable.

Examples

# from repo root
npm install
npm run example:vanilla   # http://localhost:5173
npm run example:vue       # http://localhost:5174
npm run example:react     # http://localhost:5175

Each demo shows Editor (top) + live Preview (bottom).

Project scripts

CI / CD

GitHub Actions workflows live under .github/workflows/:

Publish to npm

1. Create an npm token (Automation or granular publish for unilexical).
2. Repo → Settings → Secrets and variables → Actions → add secret NPM_TOKEN.
3. Bump version in package.json so it matches the tag without the v prefix:
   • tag v1.0.0 → "version": "1.0.0"
4. Commit, then push a version tag:

# after version bump is committed
git tag v1.0.0
git push origin v1.0.0

5. The workflow runs: check version ↔ tag → typecheck → build → npm publish --access public --provenance.

Manual dry-run: Actions → Publish npm → Run workflow → dry_run = true.

GitHub Pages (demo)

1. Repo → Settings → Pages → Build and deployment → Source: GitHub Actions.
2. Push to main (or master); workflow builds examples/vanilla with base: /<repo>/.
3. Site: https://<owner>.github.io/<repo>/.

Architecture

UniLexical follows a three-tier split:

1. Core – Lexical editor, nodes, plugins, commands, serialization
2. Bridge – Typed EventEmitter (change, toolbarChange, …)
3. Wrappers – Vue / React / Vanilla mount only (no business logic fork)

See ARCHITECTURE.md for the full specification.

Browser support

Modern evergreen browsers (Chrome, Firefox, Safari, Edge) with ES2020+.

License

MIT © UniLexical contributors

Contributing

Issues and PRs are welcome. Please:

1. Run npm run typecheck and npm run build before submitting
2. Keep framework wrappers thin—prefer core fixes over wrapper-only hacks
3. Add or update examples when introducing user-facing APIs

Changelog

See GitHub Releases for version history (or project changelog when published).

Built with Lexical · Designed for product teams who need one editor across Vanilla, Vue, and React