@caeher/react-tiptap-editor

A feature-rich, Tailwind CSS-styled React rich text editor built on top of Tiptap.

Features

• Fully customizable and configurable
• Built-in Tailwind CSS styling (supports v4.x)
• Markdown output out of the box
• Built-in toolbar, bubble menu, slash commands, and Shiki-powered code blocks
• Read-only ContentEditorPreview for rendering saved markdown with the same stack as the editor

Installation

Install the package and its peer dependencies:

npm install @caeher/react-tiptap-editor @tiptap/core @tiptap/react @tiptap/starter-kit @tiptap/pm

[!NOTE] The package ships no bundled runtime dependencies; everything runs through declared peer dependencies, which helps avoid version conflicts in apps like Next.js.

Peer Dependencies

Ensure you have the following installed in your project:

• react (v18 or v19)
• react-dom (v18 or v19)
• @tiptap/core
• @tiptap/react
• @tiptap/starter-kit
• @tiptap/pm

Code blocks (syntax highlighting) use Shiki via tiptap-extension-code-block-shiki. If you leave config.features.codeBlock enabled (the default), install these as well:

npm install shiki tiptap-extension-code-block-shiki tiptap-markdown

The published package.json may mark shiki and tiptap-extension-code-block-shiki as optional peers, but they are required whenever code blocks are enabled.

If you encounter ERESOLVE warnings during installation, you can use the --legacy-peer-deps flag.

Tailwind Typography

This editor uses Tailwind CSS prose classes for styling. To ensure these styles are generated, you must have the @tailwindcss/typography plugin installed and configured in your project:

npm install -D @tailwindcss/typography

Configuring Tailwind CSS 4.x

To ensure the editor styles are properly applied in your project, you need to include the library's CSS. In Tailwind CSS v4, you can import the stylesheet directly into your global CSS file.

Add the following to your global index.css (or app.css):

@import "tailwindcss";
@import "@caeher/react-tiptap-editor/dist/index.css";

/* Your custom styles */

Or, if your project uses a tailwind.config.js or tailwind.config.ts (if you maintain a v4 config file structure or use the Vite plugin), make sure to include the paths to the library components so Tailwind can scan them:

export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
    // Add the library to your content paths
    "./node_modules/@caeher/react-tiptap-editor/dist/**/*.{js,ts,jsx,tsx}"
  ],
  // ...
}

Syntax highlighting (Shiki)

Fenced markdown with a language id becomes a code block with Shiki highlighting, for example:

```js
const x = 1;
```

Set config.features.codeBlock to false to disable code blocks in both the editor and ContentEditorPreview.

In the full Editor, each block can also get its own Shiki theme from the code-block toolbar. That per-block theme is stored in the serialized markdown when present.

In ContentEditorPreview, there is no toolbar: the Shiki defaultTheme follows config.theme:

| config.theme | Shiki default theme | |----------------|---------------------| | light | github-light | | dark | material-theme-darker | | system or omitted | material-theme-darker |

The preview does not read prefers-color-scheme for system. For a preview that tracks OS dark mode, resolve light vs dark in your app and pass config={{ theme: 'light' | 'dark' }} explicitly.

Per-block theme from the editor still wins when it is stored on the node.

Basic Usage

Here is a quick example of how to use the Editor component in your React application:

import { useState } from 'react';
import { Editor } from '@caeher/react-tiptap-editor';
import '@caeher/react-tiptap-editor/dist/index.css'; // You can also import the CSS directly in your entry file

function App() {
  // Note: the editor outputs markdown by default
  const [content, setContent] = useState('# Hello World!\nStart typing...');

  return (
    <div className="max-w-4xl mx-auto mt-10">
      <Editor
        content={content}
        onChange={(markdown) => setContent(markdown)}
        placeholder="Write something amazing..."
      />
    </div>
  );
}

export default App;

Content preview (read-only)

Use ContentEditorPreview to render the same markdown the editor produces, without toolbar, bubble menu, or slash commands. Shiki highlighting applies when code blocks are enabled and peers are installed.

import { useState } from 'react';
import { Editor, ContentEditorPreview } from '@caeher/react-tiptap-editor';
import '@caeher/react-tiptap-editor/dist/index.css';

function App() {
  const [content, setContent] = useState('# Title\n\n```ts\nconst ok = true;\n```');

  return (
    <div className="grid max-w-5xl gap-6 md:grid-cols-2">
      <Editor content={content} onChange={setContent} config={{ theme: 'dark' }} />
      <ContentEditorPreview content={content} config={{ theme: 'dark' }} />
    </div>
  );
}

Props Reference

<Editor />

| Prop | Type | Default | Description | |---|---|---|---| | content | string | '' | Initial markdown content of the editor. | | onChange | (markdown: string) => void | undefined | Callback fired when the content changes, returning markdown. | | placeholder | string | undefined | Placeholder text when the editor is empty. | | editable | boolean | true | Whether the editor is read-only or not. | | className | string | '' | Additional CSS classes for the editor container. | | config | Partial<EditorConfig> | {} | Advanced configuration for features and images. |

<ContentEditorPreview />

| Prop | Type | Default | Description | |---|---|---|---| | content | string | '' | Markdown source to render. | | className | string | '' | Additional CSS classes for the outer container. | | config | Partial<EditorConfig> | {} | Same shape as for Editor (features, image, theme). Slash commands are always off in preview. |

Contributing

We welcome contributions to @caeher/react-tiptap-editor! Follow these steps to set up the project locally:

1. Fork the repository Go to the repository page and click the "Fork" button.

2. Clone your fork

   git clone https://github.com/YOUR_USERNAME/react-tiptap-editor.git
   cd react-tiptap-editor

3. Install dependencies

   npm install

4. Make your changes

   • The editor components are located in src/components/editor.
   • Make sure your code follows the existing style.
   • Run npm run lint to check for formatting or linting errors.

5. Submit a Pull Request

   • Commit your changes with descriptive messages.
   • Push to your fork and submit a PR to the main branch of the original repository.