![\"Kinkin](\"assets/banner.svg\")
\n\n \n
\n ![\"npm](\"https://img.shields.io/npm/v/@blakaa/kinkin-editor?color=green\")
![\"MIT](\"https://img.shields.io/badge/license-MIT-blue.svg\"){kind=icon}
\n ![\"React](\"https://img.shields.io/badge/react-18%20%7C%2019-149eca.svg\"){kind=icon}
\n ![\"Tiptap](\"https://img.shields.io/badge/tiptap-3.31-000000.svg\"){kind=icon}
\n ![\"TypeScript](\"https://img.shields.io/badge/types-included-3178c6.svg\"){kind=icon}
\n
\n Languages:\n English ·\n Tiếng Việt ·\n 简体中文 ·\n 日本語 ·\n 한국어 ·\n Español ·\n Português (Brasil) ·\n Français ·\n Deutsch\n
\n\n# Kinkin Editor\n\n**A drop-in rich text editor for React.** A Notion-style WYSIWYG built on\n[Tiptap](https://tiptap.dev) and ProseMirror: markdown in, markdown out (or\nHTML/JSON), with slash commands, tables, images, emoji, drag-to-reorder blocks, a\ntable of contents, and an AI Assist panel that streams from whatever LLM you\npoint it at.\n\n```bash\nnpm install @blakaa/kinkin-editor\n```\n\nIt's designed to go into a React app you already have: no global CSS reset, no\nrequired Tailwind setup, no provider to mount, and no backend assumptions — image\nupload and AI are plain callbacks you supply, or leave out.\n\n**[Live demo and playground →](https://blakaalab.github.io/kinkin-editor/)** ·\n[Setup guide](https://blakaalab.github.io/kinkin-editor/#/docs) ·\n[Releases](https://github.com/blakaalab/kinkin-editor/releases)\n\n- [Features](#features)\n- [Install](#install)\n- [Quick start](#quick-start)\n- [Using it with your own Tailwind CSS](#using-it-with-your-own-tailwind-css)\n- [Theming](#theming)\n- [API reference](#api-reference)\n- [Recipes](#recipes)\n- [Troubleshooting](#troubleshooting)\n- [Licence](#licence)\n- [Local development](#local-development)\n\n---\n\n## Features\n\n**Slash menu** (type `/`): Paragraph, Heading 1–4, Bullet list, Numbered list,\nTask list, Quote, Code, Emoji, Table, Image, Video, X post, Columns (2–4), Horizontal line.\n\n**Also built in**\n\n- Markdown in and markdown out — and paste markdown to convert it to rich content\n- Emoji picker on `:`\n- Drag handle on each block to reorder; `Mod-Shift-↑/↓` to move, `Mod-Shift-D` to duplicate\n- Tables with column/row controls and drag-to-reorder\n- Columns — 2 to 4 side by side, holding any block, stacking on narrow screens\n- Link editing, code blocks, task lists, highlights, typography substitutions\n- Text alignment, text colour and highlight colour, from the toolbar or the\n selection toolbar\n- Image upload through a callback you supply\n- YouTube and TikTok embeds — from the slash menu, or paste a video link on an\n empty line. Shorts and TikToks embed upright at 9:16. Saved as the link, in\n markdown as `:::videoEmbed {src=\"…\"} :::`; the iframe is rebuilt from the\n video id on every render, so a document can't carry any other iframe\n- X (Twitter) post embeds — `/x post` from the slash menu, paste a post link on\n an empty line, or paste the embed code X gives you. Saved as the link, in\n markdown as `:::tweetEmbed {src=\"…\"} :::`; like videos, the iframe is rebuilt\n from the post id, and X's `widgets.js` never runs on your page\n- Video upload through a callback you supply — drop or paste a video file, or\n use \"Upload file\" in the `/video` field. It plays in the browser's own player\n- Resizable images and videos — drag the handle on either side; the media\n stays centred. The width is a percentage of the column, so it holds on a\n narrower page, and markdown keeps it: `{width=50%}` for images,\n `width=\"50%\"` inside a video's `{…}`\n- Streaming AI Assist — improve, continue, summarize, fix grammar, simplify,\n shorten, extend, translate, change tone, or a custom prompt\n- Table of contents via `onTocItemsChange`\n- Render saved documents without the editor — a schema-only extension list\n and a display-only stylesheet, both published separately\n- Fixed, floating-selection and mobile toolbars\n- TypeScript types included; React 18 and 19\n\n---\n\n## Install\n\n```bash\nnpm install @blakaa/kinkin-editor # or: pnpm add @blakaa/kinkin-editor\n```\n\nThat's the whole command on npm 7+ and pnpm: both read `peerDependencies` and\ninstall React and all 24 `@tiptap/*` packages for you — you don't list them.\n\n### Yarn\n\nYarn does **not** auto-install peer dependencies — neither Classic nor Berry. You\nneed them explicitly (brace expansion keeps it to two lines):\n\n```bash\nyarn add @blakaa/kinkin-editor\nyarn add react react-dom \\\n @tiptap/{core,react,pm,starter-kit,extensions,markdown,suggestion,extension-code-block,extension-code-block-lowlight,extension-emoji,extension-highlight,extension-history,extension-horizontal-rule,extension-image,extension-list,extension-mention,extension-strike,extension-table,extension-table-of-contents,extension-text-align,extension-text-style,extension-typography,extension-unique-id,extension-drag-handle-react}\n```\n\n### Why peer dependencies at all\n\nReact and ProseMirror must be **single instances**. Two copies of React gives you\n\"Invalid hook call\"; two copies of ProseMirror gives you `RangeError: Invalid\ncontent` and plugin-key collisions, because `prosemirror-model` relies on\n`instanceof` checks and a shared schema registry. Declaring them as peers is what\nmakes package managers dedupe to one copy.\n\nEvery `@tiptap/*` peer is pinned to `~3.31.3` — the version this library is built\nand tested against. Mixed Tiptap minors fail at build time, so the range stays\ndeliberately narrow and moves as a whole on each verified Tiptap upgrade.\n\n---\n\n## Quick start\n\n```tsx\nimport { useState } from \"react\";\nimport { FixedToolbar, RichTextEditor } from \"@blakaa/kinkin-editor\";\nimport \"@blakaa/kinkin-editor/style.css\";\n\nexport function Editor() {\n const [markdown, setMarkdown] = useState(\"# Hello\\n\\nStart typing.\");\n\n return (\n` and as the\nfence in markdown.\n\nThe colours themselves are editor decorations, so they never reach the saved\ndocument — `generateHTML` gives you plain code. Colour it once the HTML is in a\nDOM with `highlightCodeBlocks`, which applies the same rules the editor does:\n\n```tsx\n\"use client\";\nimport { highlightCodeBlocks } from \"@blakaa/kinkin-editor/content\";\n\nconst ref = useRef(null);\nuseEffect(() => {\n if (ref.current) highlightCodeBlocks(ref.current);\n}, [html]);\n\n\n```\n\nOn a server, run it on the same jsdom / happy-dom tree `generateHTML` needs, and\nserialise that tree's `innerHTML` instead. Running it twice is harmless.\n\n### X posts\n\nAn embedded post only knows its height once it has loaded, and reports it to\nthe page in a message. The editor listens for that; on a rendered page, call\n`resizeTweetEmbeds` once the HTML is in the DOM, or each post keeps\n`content.css`'s fixed stand-in height and may be cut off:\n\n```tsx\nimport { resizeTweetEmbeds } from \"@blakaa/kinkin-editor/content\";\n\nuseEffect(() => {\n if (ref.current) return resizeTweetEmbeds(ref.current);\n}, []);\n```\n\nIt returns the function that stops listening. Posts added to the element later\nare picked up without calling it again.\n\n### `content.css`\n\nThe display half. Content rules only — no toolbars, menus, selection or drag\naffordances, no Tailwind utilities, no `@theme` block and no reset — and every\nrule comes from the same source as the editor's, so a rendered page and the\neditor cannot look different.\n\nThree properties worth knowing:\n\n**It is scoped to one opt-in class.** Nothing is styled until you put\n`kinkin-content` (exported as `CONTENT_SCOPE_CLASS`) on the element. Font size,\nfamily and text colour are inherited, never set — every measurement is in `em`,\nso the content scales with whatever your page gives it.\n\n**It sits in a cascade layer.** Everything is inside `@layer kinkin-content`.\nUnlayered CSS beats a layer regardless of specificity, so your own rules win\nwithout `!important` or specificity games:\n\n```css\n/* No layer, so this wins over content.css — the selector doesn't have to be\n more specific than the one it's overriding. */\n.kinkin-content h1 { font-size: 2.5rem; }\n```\n\n**Every colour is a `--tt-core-*` variable, and the sheet declares none of\nthem.** Each is a `var()` with its default as the fallback, so setting a token\nanywhere above the content element themes it — including a dark mode:\n\n```css\nhtml.dark {\n --tt-core-code-bg: #232733;\n --tt-core-code-text: #e6e8ec;\n --tt-core-codeblock-bg: #1b1f27;\n --tt-core-blockquote: #5b6472;\n --tt-core-link: #7ebcfd;\n --tt-core-horizontal-line: #2b303a;\n --tt-core-table-border: #2b303a;\n --tt-core-table-header-bg: #1b1f27;\n --tt-core-table-stripe-bg: #191c23;\n --tt-core-tasklist-bg: #232733;\n --tt-core-tasklist-border: #5b6472;\n --tt-core-syntax-comment: #8b949e;\n --tt-core-syntax-keyword: #ff7b72;\n --tt-core-syntax-string: #a5d6ff;\n --tt-core-syntax-constant: #79c0ff;\n --tt-core-syntax-function: #d2a8ff;\n --tt-core-syntax-builtin: #ffa657;\n --tt-core-syntax-tag: #7ee787;\n --tt-core-syntax-addition: #aff5b4;\n --tt-core-syntax-deletion: #ffa198;\n}\n```\n\n(This is why the sheet declares no defaults on `.kinkin-content` itself: an\ninherited custom property is resolved by proximity, not specificity, so a\ndeclaration on the content element would silently beat one on `html.dark`.)\n\nTwo display-only decisions: task-list checkboxes are rendered but not\nclickable — a page has nowhere to save the click — and the `imageUpload`\nplaceholder is hidden, as are a video embed that never got its link and a\nvideo upload that never finished.\n\nOne constraint: the scope element is `white-space: pre-wrap`, matching the\neditor, so runs of spaces the author typed survive. Don't pretty-print or\nindent the generated HTML inside it — that indentation would render.\n\n---\n\n## API reference\n\n### `` | — | Escape hatch to the underlying Tiptap instance. |\n| `pageTitle` | `string` | — | Included as context in AI Assist prompts. |\n| `placeholder` | `string` | — | Empty-document placeholder. |\n\n`onChange`'s `meta.source` is `\"manual\"` for user typing and `\"conversation\"` for\nprogrammatic edits — useful for skipping autosave on non-user changes.\n\n### Toolbars\n\n| Export | Behaviour |\n| --- | --- |\n| ` {\n if (meta?.source === \"manual\") debouncedSave(value as string);\n }}\n {...rest}\n/>\n```\n\n**Read-only preview**\n\n```tsx\n/`, so\n the site build sets `base: \"/kinkin-editor/\"` — only for `command === \"build\"`,\n which leaves `npm run dev` on `/`.\n- This repo pins `@tiptap/*` to exactly 3.31.3 via `overrides` to keep one copy\n in its own tree. `overrides` are ignored when the package is installed\n elsewhere, which is why the troubleshooting note above exists.\n\n### Stack\n\nReact 19, Vite 7, Tailwind 4, TypeScript 5.9, Tiptap 3.31. The site adds\n`motion` and vendored MagicUI components — neither ships in the package.\n","readmeFilename":"README.md"}