@voilabs/mark

A modern React rich text editor library built on top of Tiptap, Tailwind CSS, Radix UI, and TypeScript.

It is designed as a reusable package rather than a demo application, and ships a polished editing shell with a formatting toolbar, slash commands, media support, paragraph styles, theme switching, translations, and a Tailwind integration helper.

Table of Contents

• Overview
• Quick Start
• Highlights
• Prerequisites
• Installation
• Tailwind Integration
• API Reference
• Development Workflow
• Build and Distribution
• Dependency Management
• Architecture
• Project Structure
• Tech Stack and Dependencies
• Contributing
• License

Overview

@voilabs/mark is a library-first editor package that exposes a ready-to-use Editor component and several supporting exports for advanced integration scenarios.

The package focuses on:

• rich text authoring with Tiptap
• consistent, modern UI primitives using Radix UI
• Tailwind-friendly styling and host-project theming
• configurable typography and named paragraph styles
• image and video insertion workflows
• English and Turkish localization support
• distribution as a typed library with multiple entry points

The editor accepts initial content as HTML or Markdown, can auto-detect the incoming format, and emits content updates as Markdown through onChange.

Quick Start

import { Editor } from "@voilabs/mark";

Basic Usage

import { useState } from "react";
import { Editor } from "@voilabs/mark";
import translations from "@voilabs/mark/translations/en-US";

export function ArticleEditor() {
    const [value, setValue] = useState("# Hello world");

    return (
        <Editor
            value={value}
            format="auto"
            theme="auto"
            translations={translations}
            onChange={setValue}
        />
    );
}

With Upload Support

import { Editor } from "@voilabs/mark";

async function uploadFile(file: File): Promise<{ url: string }> {
    const formData = new FormData();
    formData.append("file", file);

    const response = await fetch("/api/upload", {
        method: "POST",
        body: formData,
    });

    if (!response.ok) {
        throw new Error("Upload failed");
    }

    return response.json();
}

export function MediaEnabledEditor() {
    return (
        <Editor
            value="Start writing..."
            onUpload={uploadFile}
            onChange={(markdown) => {
                console.log(markdown);
            }}
        />
    );
}

With Custom Paragraph Styles

import {
    Editor,
    DEFAULT_PARAGRAPH_STYLES,
    type ParagraphStyle,
} from "@voilabs/mark";

const customStyles: ParagraphStyle[] = [
    ...DEFAULT_PARAGRAPH_STYLES,
    {
        id: "callout",
        label: "Callout",
        preview: "Callout",
        type: "blockquote",
        fontSize: "18px",
        fontWeight: "600",
        color: "#0f172a",
    },
];

export function StyledEditor() {
    return <Editor styles={customStyles} />;
}

With Translation Overrides

import { Editor } from "@voilabs/mark";
import trTR from "@voilabs/mark/translations/tr-TR";

export function TurkishEditor() {
    return (
        <Editor
            translations={{
                ...trTR,
                placeholder: "Yazmaya baslayin",
            }}
        />
    );
}

Highlights

Editing Experience

• Toolbar with undo/redo, headings, lists, quote, code block, inline marks, text alignment, links, highlight colors, font family, and font size controls
• Slash command menu triggered by / for quick insertion of text blocks, headings, lists, images, tables, quotes, and code blocks
• Word count footer with zoom controls and fullscreen toggle
• Global drag handle for block insertion, duplication, reordering, anchor-link copying, color actions, and deletion

Media Support

• Custom image node implementation with resize handles, crop mode, rotation, object-fit frame mode, pan controls, upload state, and alt text editing
• Video node support for uploaded video insertion
• Drag-and-drop and paste image upload handling when an onUpload callback is provided
• Slash-command image insertion with file picker support or URL prompt fallback

Styling and Customization

• Tailwind-based UI with overridable class slots via EditorClassNames
• Built-in light and dark themes with persisted theme preference in cookie/localStorage when theme="auto"
• Named paragraph styles with a Word-like quick style gallery
• Right-click style editing with local persistence in localStorage
• Translation override support through translations

Packaging

• Typed library output generated by Vite and vite-plugin-dts
• ESM, UMD, and declaration outputs under dist

Prerequisites

Before using or developing this package, make sure you have:

• Node.js 20 or newer recommended
• npm 10 or newer recommended
• a React application using React 19
• TypeScript 5 if you want full type support

If you plan to use the Tailwind helper export, your host application should also be configured for Tailwind CSS.

Installation

Library Consumers

Install the package and its peer dependencies:

npm install @voilabs/mark react react-dom typescript

Tailwind Plugin Consumers

If you use the exported Tailwind plugin helper, also ensure your project has the typography plugin available:

npm install @tailwindcss/typography

Repository Setup

To work on the library itself:

bun install

Tailwind Integration

The editor UI is built with Tailwind utility classes. In host projects, the package export @voilabs/mark/plugin can help Tailwind discover the library's compiled class usage.

Example configuration:

import editorTailwindPlugin from "@voilabs/mark/plugin";

export default {
    plugins: [editorTailwindPlugin],
};

What the plugin does:

• resolves the installed package path
• points Tailwind content scanning to the package dist files
• enables tailwindcss-animate
• enables @tailwindcss/typography

API Reference

Editor

import { Editor } from "@voilabs/mark";

EditorProps

| Prop | Type | Description | | -------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | | value | string | Initial editor content. Supports HTML or Markdown depending on format. | | onChange | (value: string) => void | Receives Markdown output whenever the editor updates. | | format | "html" \| "markdown" \| "auto" | Controls how the initial value is interpreted. auto detects Markdown-like input. | | theme | "light" \| "dark" \| "auto" | Forces a theme or enables persisted user switching. | | onUpload | (file: File) => Promise<{ url: string }> | Upload handler used by toolbar uploads, slash-command image insertion, paste uploads, and drag/drop uploads. | | disableVideoUpload | boolean | Disables video upload actions in the toolbar. | | disableImageUpload | boolean | Disables image upload actions and image upload-driven insertion flows. | | classNames | EditorClassNames | Fine-grained class slot overrides for editor shell, toolbar, menus, footer, drag handle, and image UI. | | translations | Partial<EditorTranslations> | Partial translation override merged over built-in English strings. | | styles | ParagraphStyle[] | Replaces the default quick style set shown in the toolbar style gallery. |

ParagraphStyle

Each paragraph style can define:

• id
• label
• preview
• type
• level
• fontFamily
• fontSize
• fontWeight
• fontStyle
• color
• letterSpacing
• lineHeight
• textTransform

EditorClassNames

EditorClassNames exposes slot-level styling hooks for nearly every visible part of the editor.

Shell and Content Slots

| Slot | Purpose | | ----------------- | ------------------------------ | | root | Outer editor wrapper | | content | Main scrollable content region | | contentScroller | Content scrolling container | | contentInner | Inner centered content wrapper | | editorContent | EditorContent host container | | prose | Tiptap prose typography layer |

Footer Slots

| Slot | Purpose | | ------------------------ | ------------------------------------ | | footer | Footer root container | | footerWordCount | Word count label area | | footerControls | Footer controls wrapper | | footerButton | Shared footer button styling | | footerButtonDisabled | Disabled footer button state | | footerZoomGroup | Zoom controls group | | footerZoomButton | Zoom increment and decrement buttons | | footerZoomValue | Zoom percentage button | | footerFullscreenButton | Fullscreen toggle button |

Toolbar Slots

| Slot | Purpose | | ----------------------- | -------------------------------- | | toolbar | Toolbar root container | | toolbarInner | Toolbar scroll container | | toolbarGroup | Toolbar button group wrapper | | toolbarButton | Shared toolbar button styling | | toolbarButtonActive | Active toolbar button state | | toolbarButtonDisabled | Disabled toolbar button state | | toolbarButtonIcon | Toolbar button icon wrapper | | toolbarTrigger | Dropdown trigger buttons | | toolbarTriggerActive | Active dropdown trigger state | | toolbarTriggerIcon | Dropdown trigger icon wrapper | | toolbarTriggerLabel | Dropdown trigger label text | | toolbarTriggerChevron | Dropdown trigger chevron | | toolbarSeparator | Separator between toolbar groups | | toolbarFileInput | Hidden media file input | | toolbarUploadButton | Upload button | | toolbarUploadIcon | Upload button icon | | toolbarUploadLabel | Upload button label |

Style Bar Slots

| Slot | Purpose | | -------------------- | ----------------------------- | | styleBar | Quick style gallery container | | styleBarItem | Individual style card | | styleBarItemActive | Active style card |

Style Editor Slots

| Slot | Purpose | | ---------------------- | ------------------------------------ | | styleEditPopover | Right-click style edit popover | | styleEditInput | Inputs inside the style editor | | styleEditSaveButton | Save button inside the style editor | | styleEditResetButton | Reset button inside the style editor |

Font Family Slots

| Slot | Purpose | | ----------------------------- | ---------------------------- | | toolbarFontFamilyTrigger | Font family combobox trigger | | toolbarFontFamilyPopover | Font family popover body | | toolbarFontFamilySearch | Font family search input | | toolbarFontFamilyList | Font family list container | | toolbarFontFamilyItem | Individual font option | | toolbarFontFamilyItemActive | Active font option |

Font Size Slots

| Slot | Purpose | | ------------------------------ | ------------------------------ | | toolbarFontSizeControl | Font size control wrapper | | toolbarFontSizeControlActive | Active font size control state | | toolbarFontSizeIcon | Font size icon wrapper | | toolbarFontSizeInput | Font size text input | | toolbarFontSizeUnit | Font size unit label | | toolbarFontSizeStepButton | Increase and decrease buttons | | toolbarFontSizeResetButton | Reset font size button |

Link Popover Slots

| Slot | Purpose | | ------------------------- | ---------------------------- | | toolbarLinkButton | Link toolbar button | | toolbarLinkPopoverBody | Link popover content wrapper | | toolbarLinkPopoverLabel | Link popover heading | | toolbarLinkInput | Link URL input | | toolbarLinkActions | Link action buttons wrapper | | toolbarLinkApplyButton | Apply link button | | toolbarLinkUnlinkButton | Remove link button |

Highlight Slots

| Slot | Purpose | | ------------------------------ | -------------------------------- | | toolbarHighlightButton | Highlight toolbar button | | toolbarHighlightIndicator | Color indicator under the button | | toolbarHighlightPopoverBody | Highlight palette popover body | | toolbarHighlightPopoverLabel | Highlight palette label | | toolbarHighlightGrid | Highlight swatch grid | | toolbarHighlightSwatch | Individual highlight swatch | | toolbarHighlightSwatchActive | Active highlight swatch | | toolbarHighlightClearButton | Clear highlight button |

Shared Overlay Slots

| Slot | Purpose | | --------------------------- | --------------------------------- | | tooltipContent | Tooltip content container | | tooltipArrow | Tooltip arrow | | popoverContent | Shared popover content container | | dropdownContent | Main dropdown menu content | | dropdownSubContent | Nested dropdown menu content | | dropdownSubTrigger | Nested dropdown trigger item | | dropdownSubTriggerChevron | Nested dropdown chevron | | dropdownItem | Standard dropdown item | | dropdownItemActive | Active dropdown item state | | dropdownItemIcon | Dropdown item icon | | dropdownItemLabel | Dropdown item label | | dropdownItemCheck | Dropdown selected-state checkmark | | dropdownCheckboxItem | Checkbox dropdown item | | dropdownRadioItem | Radio dropdown item | | dropdownIndicator | Dropdown indicator wrapper | | dropdownLabel | Dropdown section label | | dropdownSeparator | Dropdown separator | | dropdownShortcut | Dropdown shortcut hint text |

Slash Command Slots

| Slot | Purpose | | ------------------------ | ---------------------------- | | slashCommandMenu | Slash command menu container | | slashCommandItem | Slash command item | | slashCommandItemActive | Active slash command item | | slashCommandIcon | Slash command icon wrapper | | slashCommandTitle | Slash command item label | | slashCommandEmpty | Empty state wrapper | | slashCommandEmptyIcon | Empty state icon |

Drag Handle Slots

| Slot | Purpose | | ----------------------------- | ----------------------------------- | | dragHandleRoot | Floating drag handle root | | dragHandleAddButton | Add-block button | | dragHandleMenuButton | Grip/menu button | | dragHandleMenuContent | Drag handle dropdown content | | dragHandleSubContent | Nested drag handle dropdown content | | dragHandleColorSectionLabel | Text/background color section label | | dragHandleColorTextPreview | Text color preview glyph | | dragHandleColorSwatch | Background color swatch | | dragHandleCheckIcon | Selected-state check icon | | dragHandleDeleteItem | Delete item styling |

Image Node Slots

| Slot | Purpose | | ------------------------------ | ---------------------------- | | imageNodeWrapper | Outer image node wrapper | | imageContainer | Image selection frame | | imageCropArea | Crop area wrapper | | imageCropToolbar | Crop mode toolbar | | imageCropButton | Shared crop toolbar button | | imageCropCancelButton | Cancel crop button | | imageCropApplyButton | Apply crop button | | imageFrame | Image frame container | | imageElement | Rendered <img> element | | imageLoadingOverlay | Upload/loading overlay | | imageLoadingBox | Loader badge container | | imageLoadingIcon | Loader icon | | imagePanHintOverlay | Pan hint overlay | | imagePanHint | Pan hint text | | imageToolbar | Image hover toolbar | | imageToolbarButton | Shared image toolbar button | | imageToolbarSeparator | Divider inside image toolbar | | imageDeleteButton | Image delete button | | imageAltButton | Alt text button | | imageAltPopover | Alt text popover body | | imageAltLabel | Alt text popover label | | imageAltInput | Alt text input | | imageAltActions | Alt text action row | | imageAltApplyButton | Apply alt text button | | imageAltClearButton | Clear alt text button | | imageResizeHandle | Shared resize handle styling | | imageResizeHandleRight | Right resize handle | | imageResizeHandleBottom | Bottom resize handle | | imageResizeHandleBottomRight | Bottom-right resize handle | | imageModeBadge | Mode hint wrapper | | imageModeText | Mode hint label |

This API is intended for design system integration without forcing a fork of the editor internals.

Translations

The library ships with:

• en-US
• tr-TR

You can either import a full locale object or pass a partial object to override selected labels.

Development Workflow

This repository is configured as a library project, not as a local preview app.

Install Dependencies

bun install

Development Build Watch

bun run dev

This runs:

vite build --watch

Use this mode when you want incremental rebuilds of the library output while developing the package.

Production Build

bun run build

This runs:

vite build && tsc -p tsconfig.build.json

The command generates JavaScript bundles and declaration files into dist/.

Build and Distribution

The Vite configuration builds multiple library entry points:

• src/index.ts
• src/plugin.ts
• src/translations/en-US.ts
• src/translations/tr-TR.ts

The package metadata exposes:

• main editor entry
• Tailwind plugin entry
• locale entries

Distributed assets include:

• ESM bundles
• UMD bundles
• .d.ts type declarations

The package is configured to publish:

• dist
• README.md
• LICENSE
• package.json

Dependency Management

Peer Dependencies

The package declares the following peers:

• react
• react-dom
• typescript

Runtime Dependencies

The runtime layer relies heavily on:

• Tiptap extensions and editor packages
• Radix UI primitives
• Tailwind merge helpers
• icon and motion libraries
• media and popup utilities such as react-easy-crop and tippy.js

Development Dependencies

Development and build-time tooling includes:

• Babel and Rollup-related packages
• Vite and React integration tooling
• TypeScript
• declaration generation plugins

Lockfiles

The repository currently includes both package-lock.json and bun.lock, which suggests npm and Bun have both been used during development. This README uses Bun for repository workflows and npm for consumer installation examples.

Architecture

The codebase is organized as a reusable component library with a single primary editor shell and a set of supporting modules.

High-Level Design

1. src/components/Editor.tsx creates the Tiptap editor instance and composes the full editor shell.
2. src/components/editor/Toolbar.tsx provides the main authoring controls and style management UI.
3. src/components/editor/GlobalDragHandleMenu.tsx adds block-level actions beside the editing surface.
4. src/components/editor/extensions/* defines custom Tiptap extensions for images, video, font size, font family, and extra text-style attributes.
5. src/components/editor/slash-command/* implements the / suggestion system.
6. src/components/editor/EditorContext.tsx shares theme, translations, class names, and styles with nested UI primitives.
7. src/plugin.ts exports a Tailwind helper plugin intended to help host apps include the editor's utility classes.

Content Flow

The editor follows this runtime flow:

1. Initial value is read as HTML, Markdown, or auto-detected content.
2. Tiptap extensions are registered, including the custom image/video and typography extensions.
3. User actions update the internal ProseMirror document.
4. onChange is called with editor.getMarkdown().

Important behavior:

• Input supports HTML, Markdown, or auto-detection via the format prop.
• Output is Markdown on every update, regardless of the original input format.
• Auto theme mode persists the chosen theme using the VOILABS_REACT_EDITOR_THEME key.
• Style overrides are stored locally using the voilabs-editor-style-overrides key.

Extensibility Points

• onUpload for custom media upload pipelines
• styles for custom paragraph style sets
• classNames for granular visual overrides
• translations for partial locale overrides
• exported Tiptap extensions such as AdvancedImage, FontSize, and Video

Project Structure

editor/
|- src/
|  |- components/
|  |  |- Editor.tsx
|  |  |- editor/
|  |  |  |- EditorContext.tsx
|  |  |  |- Toolbar.tsx
|  |  |  |- StyleBar.tsx
|  |  |  |- StyleEditPopover.tsx
|  |  |  |- GlobalDragHandleMenu.tsx
|  |  |  |- classNames.ts
|  |  |  |- paragraphStyles.ts
|  |  |  |- translations.ts
|  |  |  |- useStyleStorage.ts
|  |  |  |- extensions/
|  |  |  |  |- AdvancedImage.tsx
|  |  |  |  |- ImageNodeView.tsx
|  |  |  |  |- FontFamily.ts
|  |  |  |  |- FontSize.ts
|  |  |  |  |- TextStyleAttributes.ts
|  |  |  |  `- Video.tsx
|  |  |  `- slash-command/
|  |  |     |- commands.ts
|  |  |     |- commands-list.tsx
|  |  |     `- suggestion.tsx
|  |  `- ui/
|  |     |- Dropdown.tsx
|  |     |- DropdownMenu.tsx
|  |     |- Popover.tsx
|  |     `- Tooltip.tsx
|  |- lib/
|  |  `- utils.ts
|  |- translations/
|  |  |- en-US.ts
|  |  `- tr-TR.ts
|  |- index.ts
|  `- plugin.ts
|- package.json
|- vite.config.ts
|- tsconfig.json
`- tsconfig.build.json

Tech Stack and Dependencies

Core Runtime

• React 19
• Tiptap 3 ecosystem
• ProseMirror through @tiptap/pm
• Tailwind CSS 4
• Radix UI popover, dropdown menu, and tooltip primitives
• lucide-react for editor icons
• react-easy-crop for image cropping
• tippy.js for slash command popup positioning

Build Tooling

• Vite library mode
• TypeScript 5
• vite-plugin-dts for declaration generation
• @vitejs/plugin-react
• @tailwindcss/vite

Noteworthy Implementation Details

• The editor uses a custom image node implementation instead of the default Tiptap image extension.
• The Video extension renders native HTML <video> nodes with controls enabled.
• The toolbar uses context-aware command selection so inline formatting can apply to the current word even when no explicit range is selected.
• The drag handle menu performs block-level actions by resolving the top-level node under the cursor.
• The Tailwind helper plugin tries to resolve the installed package path dynamically and scans the built dist files for content extraction.

Contributing

Contributions should preserve the package's library-first design, typed public API, and editor usability.

Recommended contribution process:

1. Fork or branch from the latest mainline source.
2. Install dependencies with npm install.
3. Make focused changes with clear intent.
4. Verify the package builds successfully with npm run build.
5. Update documentation when behavior or public API changes.
6. Open a pull request with a concise explanation of the change.

Suggested contribution guidelines:

• keep public API changes intentional and documented
• avoid breaking translation keys without updating shipped locales
• preserve Markdown output behavior unless a deliberate API change is introduced
• keep Tailwind class slot compatibility in mind when changing UI structure
• prefer incremental, reviewable pull requests

At the moment, the repository does not define dedicated lint or test scripts in package.json, so build validation is the primary verification step.

License

This project is licensed under the MIT License.

See LICENSE for the full text.