Novel

https://github.com/steven-tey/novel
Admin
Novel is an open-source Notion-style WYSIWYG editor with AI-powered autocompletions.
Tokens:59,856
Snippets:366
Trust Score:10
License:Apache-2.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install dependencies and run dev server

Source: https://github.com/steven-tey/novel/blob/main/README.md

Run these commands in the project root to install dependencies and start the development server locally. Requires the OPENAI_API_KEY and BLOB_READ_WRITE_TOKEN environment variables to be set first.

```bash
pnpm i
pnpm dev
```

--------------------------------

### Client usage example for POST /api/upload

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/endpoints.md

Example of how the reference app calls the upload endpoint using fetch. It sends the file as the request body with content-type and x-vercel-filename headers, and handles success (200) and unauthorized (401) responses.

```tsx
// apps/web/components/tailwind/image-upload.ts
const res = await fetch("/api/upload", {
  method: "POST",
  headers: {
    "content-type": file?.type || "application/octet-stream",
    "x-vercel-filename": file?.name || "image.png",
  },
  body: file,
});
if (res.status === 200) {
  const { url } = (await res.json()) as { url: string };
  // resolve(url) after preloading
} else if (res.status === 401) {
  // fall back to reading the file locally (data URL)
}
```

--------------------------------

### renderItems usage

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/extensions-slash-command.md

Shows how to configure the slash command with renderItems. The first example appends the popup to document.body; the second constrains it to a container using a ref.

```tsx
import { renderItems } from "novel";

Command.configure({
  suggestion: {
    items: () => items,
    render: renderItems, // popup appended to document.body
  },
});

// or constrain the popup to a container:
Command.configure({
  suggestion: {
    items: () => items,
    render: renderItems(containerRef),
  },
});
```

--------------------------------

### Command

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/extensions-slash-command.md

Creates a Tiptap extension that enables a slash-command suggestion system. It installs `@tiptap/suggestion` with the trigger character `/` and renders a command palette popup at the caret.

```APIDOC
## Command

### Description
Creates a Tiptap extension that enables a slash-command suggestion system. It installs `@tiptap/suggestion` with the trigger character `/` and renders a command palette popup at the caret.

### Method
N/A (Tiptap Extension)

### Endpoint
N/A (Tiptap Extension)

### Parameters
#### Configuration Options
- `suggestion.char` (string) - Optional - Default: `"/"` - Trigger character; typing it opens the popup.
- `suggestion.command` (function) - Optional - Default: `({ editor, range, props }) => props.command({ editor, range })` - Default forwards to `props.command` — i.e. the `command` on the matched `SuggestionItem`.
- `suggestion.items` (function) - Optional - Must be supplied via `.configure()` - Returns an array of `SuggestionItem` objects.
- `suggestion.render` (function) - Optional - Must be supplied via `.configure()` - Typically `renderItems`.
- any other `SuggestionOptions` - Optional - Passed through to `Suggestion()`.

### Request Example
```tsx
import { Command, createSuggestionItems, renderItems, type SuggestionItem } from "novel";

const suggestionItems = createSuggestionItems([
  {
    title: "Heading 2",
    description: "Medium section heading.",
    icon: <span>H2</span>,
    searchTerms: ["subtitle", "medium"],
    command: ({ editor, range }) => {
      editor.chain().focus().deleteRange(range).setNode("heading", { level: 2 }).run();
    },
  },
]);

export const slashCommand = Command.configure({
  suggestion: {
    items: () => suggestionItems,
    render: renderItems,
  },
});
```

### Response
#### Success Response
Returns a Tiptap `Extension` that can be added to the extensions array.

#### Response Example
```ts
const Command = Extension.create({
  name: "slash-command",
  addOptions() {
    return {
      suggestion: {
        char: "/",
        command: ({ editor, range, props }) => {
          props.command({ editor, range });
        },
      } as SuggestionOptions,
    };
  },
  addProseMirrorPlugins() {
    return [
      Suggestion({
        editor: this.editor,
        ...this.options.suggestion,
      }),
    ];
  },
});
```
```

--------------------------------

### Basic formatting toolbar with EditorBubble

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/editor-bubble.md

Basic usage example for EditorBubble and EditorBubbleItem. It creates a formatting toolbar with Bold and Italic buttons. The component returns null if no editor is available.

```tsx
import { EditorBubble, EditorBubbleItem, useEditor } from "novel";

export function BubbleMenu() {
  const { editor } = useEditor();
  if (!editor) return null;

  return (
    <EditorBubble className="flex w-fit rounded-md border bg-background shadow-xl">
      <EditorBubbleItem onSelect={() => editor.chain().focus().toggleBold().run()}>
        Bold
      </EditorBubbleItem>
      <EditorBubbleItem onSelect={() => editor.chain().focus().toggleItalic().run()}>
        Italic
      </EditorBubbleItem>
    </EditorBubble>
  );
}
```

--------------------------------

### Create slash-command extension

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/extensions-slash-command.md

Defines the slash-command Tiptap extension that installs @tiptap/suggestion with char "/" and a default command that forwards to props.command. The suggestion options are typed as SuggestionOptions from @tiptap/suggestion.

```ts
const Command = Extension.create({
  name: "slash-command",
  addOptions() {
    return {
      suggestion: {
        char: "/",
        command: ({ editor, range, props }) => {
          props.command({ editor, range });
        },
      } as SuggestionOptions,
    };
  },
  addProseMirrorPlugins() {
    return [
      Suggestion({
        editor: this.editor,
        ...this.options.suggestion,
      }),
    ];
  },
});
```

--------------------------------

### Export markdown with getAllContent

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/markdown-utils.md

Basic usage of `getAllContent` to export the editor content as markdown and copy it to the clipboard. The editor instance must be of type `EditorInstance` and have the `MarkdownExtension` installed.

```ts
import { getAllContent } from "novel";

function exportMarkdown(editor: EditorInstance) {
  const md = getAllContent(editor);
  navigator.clipboard?.writeText(md);
}
```

--------------------------------

### getAllContent

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/markdown-utils.md

Serializes the entire editor document to a markdown string. Requires the editor to have the MarkdownExtension installed.

```APIDOC
## getAllContent

### Description
Returns the full document content from the editor serialized to markdown format.

### Function Signature
ts
export const getAllContent = (editor: EditorInstance) => string;


### Parameters
- **editor** (EditorInstance) - Required - Editor instance; requires `MarkdownExtension` for `editor.storage.markdown`.

### Returns
- **string** - The full document serialized to markdown.

### Throws
Same `storage.markdown` precondition as `getPrevText`.

### Usage — basic
ts
import { getAllContent } from "novel";

function exportMarkdown(editor: EditorInstance) {
  const md = getAllContent(editor);
  navigator.clipboard?.writeText(md);
}


### Usage — comparing serialization to the app's persistence
ts
window.localStorage.setItem("novel-content", JSON.stringify(editor.getJSON()));
window.localStorage.setItem("html-content", highlightCodeblocks(editor.getHTML()));
window.localStorage.setItem("markdown", editor.storage.markdown.getMarkdown());


### Related
- Both markdown helpers depend on `MarkdownExtension` — see [extensions-bundled.md](extensions-bundled.md).
- Types used: `EditorInstance`, `Node`/`Fragment` from `@tiptap/pm/model` (inline-expanded in [types.md](../types.md)).
```

--------------------------------

### EditorBubble

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/editor-bubble.md

Documentation for the EditorBubble component, including its props, behavior, and usage example.

```APIDOC
## EditorBubble

### Description
Renders a floating selection menu (bubble) bound to the current editor via `useCurrentEditor`. It wraps Tiptap's `BubbleMenu` and includes built-in `shouldShow` logic to hide the menu when the editor is not editable, the selection is empty, the active node is an image, or the selection is a node selection (drag handles).

### Component Signature
```tsx
export interface EditorBubbleProps extends Omit<BubbleMenuProps, "editor"> {
  readonly children: ReactNode;
}

export const EditorBubble = forwardRef<HTMLDivElement, EditorBubbleProps>(
  ({ children, tippyOptions, ...rest }, ref) => { ... }
);
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `children` | `ReactNode` | yes | — | Menu content (buttons, `EditorBubbleItem`s, custom UI) |
| `tippyOptions` | `Partial<Props>` + `placement` support | no | `{ onCreate (attaches blur guard), moveTransition: "transform 0.15s ease-out" }` | [tippy.js](https://atomiks.github.io/tippyjs/) options; spread last into the tippy config, so `placement`, `onHidden`, `appendTo`, etc. override defaults. `placement` changes are also pushed to the live tippy instance |
| `shouldShow` | `(props: { editor: Editor; state: EditorState; ... }) => boolean` | no | built-in logic (see above) | `BubbleMenuProps["shouldShow"]`; passed through via `...rest` |
| everything else from `BubbleMenuProps` except `editor` | — | no | — | e.g. `className` (applied to the wrapping `<div>`), `pluginKey`, `updateDelay` |

### Returns
Renders `null` when `useCurrentEditor()` returns no editor; otherwise a `<div ref={ref}>` wrapping the Tiptap `BubbleMenu`. Ref: `forwardRef<HTMLDivElement, EditorBubbleProps>`.

### Usage — basic (formatting toolbar)
```tsx
import { EditorBubble, EditorBubbleItem, useEditor } from "novel";

export function BubbleMenu() {
  const { editor } = useEditor();
  if (!editor) return null;

  return (
    <EditorBubble className="flex w-fit rounded-md border bg-background shadow-xl">
      <EditorBubbleItem onSelect={() => editor.chain().focus().toggleBold().run()}>
        Bold
      </EditorBubbleItem>
      <EditorBubbleItem onSelect={() => editor.chain().focus().toggleItalic().run()}>
        Italic
      </EditorBubbleItem>
    </EditorBubble>
  );
}
```
```

--------------------------------

### createSuggestionItems usage

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/extensions-slash-command.md

Example of importing and using createSuggestionItems to define a palette with a single item. The icon is a React element.

```ts
import { createSuggestionItems } from "novel";

const items = createSuggestionItems([{ title: "Text", description: "Plain text.", icon: <span /> }]);
```

--------------------------------

### Configure slash-command with items and renderer

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/extensions-slash-command.md

Registers the slash-command extension with a suggestion item list and renderer. The example defines a single item for Heading 2 that deletes the range and sets a heading node; the configured slashCommand is meant to be added to the extensions array and rendered inside EditorContent.

```tsx
import { Command, createSuggestionItems, renderItems, type SuggestionItem } from "novel";

const suggestionItems = createSuggestionItems([
  {
    title: "Heading 2",
    description: "Medium section heading.",
    icon: <span>H2</span>,
    searchTerms: ["subtitle", "medium"],
    command: ({ editor, range }) => {
      editor.chain().focus().deleteRange(range).setNode("heading", { level: 2 }).run();
    },
  },
]);

export const slashCommand = Command.configure({
  suggestion: {
    items: () => suggestionItems,
    render: renderItems,
  },
});
```

--------------------------------

### getAllContent: serialize editor content to markdown

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/markdown-utils.md

This function serializes the entire editor document to a markdown string. It requires the editor to have the `MarkdownExtension` installed to access `editor.storage.markdown`. Returns the full document as a string.

```ts
// Get all content from the editor in markdown format
export const getAllContent = (editor: EditorInstance) => {
  const fragment = editor.state.doc.content;
  const doc = editor.state.doc.copy(fragment);

  return editor.storage.markdown.serializer.serialize(doc) as string;
};
```

--------------------------------

### getPrevText utility

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/markdown-utils.md

Defines the `getPrevText` utility that returns the markdown text before a given document position. It iterates over the editor's document nodes, collects those before the position, and serializes them via `editor.storage.markdown.serializer`. The `EditorInstance` type is `Editor` from `@tiptap/core`, and requires the `MarkdownExtension` (tiptap-markdown) to be installed; otherwise, accessing `editor.storage.markdown` throws at runtime.

```ts
// Get the text before a given position in markdown format
export const getPrevText = (editor: EditorInstance, position: number) => {
  const nodes: Node[] = [];
  editor.state.doc.forEach((node, pos) => {
    if (pos >= position) return false;
    nodes.push(node);
    return true;
  });
  const fragment = Fragment.fromArray(nodes);
  const doc = editor.state.doc.copy(fragment);

  return editor.storage.markdown.serializer.serialize(doc) as string;
};
```

--------------------------------

### Usage: addAIHighlight with custom color

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/extensions-ai-highlight.md

Example usage of `addAIHighlight`. It imports the function and `useEditor` from `novel`, obtains the editor instance, and applies an AI highlight with a custom yellow color (`#ffd40066`) if the editor exists. The context implies this is called on editor focus.

```tsx
import { addAIHighlight, useEditor } from "novel";

function onFocus() {
  const { editor } = useEditor();
  if (editor) addAIHighlight(editor, "#ffd40066");
}

```

--------------------------------

### Success response JSON for POST /api/upload

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/endpoints.md

Example of the JSON response returned on a successful upload (HTTP 200). The response is a Vercel Blob PutBlobResult object; the app consumes the 'url' field.

```json
{
  "url": "https://<blob-public-url>",
  "downloadUrl": "https://<blob-public-url>?download=1",
  "pathname": "filename.png",
  "contentType": "image/png",
  "contentDisposition": "attachment; filename=\"filename.png\""
}
```

--------------------------------

### Basic usage of Twitter extension with setTweet command

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/extensions-twitter.md

Basic usage: import Twitter and EditorContent from novel, add Twitter to extensions, and insert a tweet via the setTweet command. The command returns false for invalid URLs, as shown with the example that returns false.

```tsx
import { Twitter, EditorContent } from "novel";

<EditorContent extensions={[Twitter]} />;

// insert a tweet:
editor.chain().focus().setTweet({ src: "https://x.com/seanpk/status/1800145949580517852" }).run();
// invalid URL → command returns false, nothing inserted:
const ok = editor.chain().focus().setTweet({ src: "https://twitter.com/user/status/1" }).run(); // false
```

--------------------------------

### EditorBubble component implementation

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/editor-bubble.md

Implementation of the EditorBubble component. It wraps Tiptap's BubbleMenu and uses useCurrentEditor to get the editor. The built-in shouldShow logic hides the menu when the editor is not editable, the selection is empty, the active node is an image, or the selection is a node selection. tippyOptions are merged last, allowing callers to override defaults; placement changes are pushed to the live tippy instance via an effect.

```tsx
export interface EditorBubbleProps extends Omit<BubbleMenuProps, "editor"> {
  readonly children: ReactNode;
}

export const EditorBubble = forwardRef<HTMLDivElement, EditorBubbleProps>(
  ({ children, tippyOptions, ...rest }, ref) => {
    const { editor: currentEditor } = useCurrentEditor();
    const instanceRef = useRef<Instance<Props> | null>(null);

    useEffect(() => {
      if (!instanceRef.current || !tippyOptions?.placement) return;

      instanceRef.current.setProps({ placement: tippyOptions.placement });
      instanceRef.current.popperInstance?.update();
    }, [tippyOptions?.placement]);

    const bubbleMenuProps: Omit<BubbleMenuProps, "children"> = useMemo(() => {
      const shouldShow: BubbleMenuProps["shouldShow"] = ({ editor, state }) => {
        const { selection } = state;
        const { empty } = selection;

        // don't show bubble menu if:
        // - the editor is not editable
        // - the selected node is an image
        // - the selection is empty
        // - the selection is a node selection (for drag handles)
        if (!editor.isEditable || editor.isActive("image") || empty || isNodeSelection(selection)) {
          return false;
        }
        return true;
      };

      return {
        shouldShow,
        tippyOptions: {
          onCreate: (val) => {
            instanceRef.current = val;

            instanceRef.current.popper.firstChild?.addEventListener("blur", (event) => {
              event.preventDefault();
              event.stopImmediatePropagation();
            });
          },
          moveTransition: "transform 0.15s ease-out",
          ...tippyOptions,
        },
        editor: currentEditor,
        ...rest,
      };
    }, [rest, tippyOptions]);

    if (!currentEditor) return null;

    return (
      // We need to add this because of https://github.com/ueberdosis/tiptap/issues/2658
      <div ref={ref}>
        <BubbleMenu {...bubbleMenuProps}>{children}</BubbleMenu>
      </div>
    );
  },
);

EditorBubble.displayName = "EditorBubble";
```

--------------------------------

### CustomKeymap usage within a full extension list

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/extensions-custom-keymap.md

Shows how to include CustomKeymap alongside StarterKit and MarkdownExtension in the extensions array.

```tsx
<EditorContent extensions={[StarterKit, CustomKeymap, MarkdownExtension]} />;
```

--------------------------------

### EditorBubble - Dynamic Placement and Hidden Handler

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/editor-bubble.md

Shows how to use EditorBubble with tippyOptions for dynamic placement and an onHidden handler to reset state and clear highlights.

```APIDOC
## EditorBubble - Dynamic Placement and Hidden Handler

### Description
Configures the EditorBubble's tippy popup with dynamic placement and a hidden handler that resets state and clears highlights.

### Usage Example
```tsx
import { EditorBubble, useEditor } from "novel";

export function MenuWithState(props: { open: boolean; onOpenChange: (v: boolean) => void }) {
  const { editor } = useEditor();

  return (
    <EditorBubble
      tippyOptions={{
        placement: props.open ? "bottom-start" : "top",
        onHidden: () => {
          props.onOpenChange(false);
          editor?.chain().unsetHighlight().run();
        },
      }}
      className="flex w-fit max-w-[90vw] overflow-hidden rounded-md border bg-background shadow-xl"
    >
      {props.children}
    </EditorBubble>
  );
}
```

### Notes
- The reference app does this in `apps/web/components/tailwind/generative/generative-menu-switch.tsx`, pairing the flip to `bottom-start` while the AI selector is open.
```

--------------------------------

### EditorContent

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/editor-root-and-content.md

Documentation for the EditorContent component, including its props, usage examples, and related APIs.

```APIDOC
## EditorContent

### Description
A React component that wraps Tiptap's `EditorProvider` to provide the editable surface. It forwards all editor props except `content`, which is replaced by `initialContent`.

### Component Signature
```tsx
export type EditorContentProps = Omit<EditorProviderProps, "content"> & {
  readonly children?: ReactNode;
  readonly className?: string;
  readonly initialContent?: JSONContent;
};

export const EditorContent = forwardRef<HTMLDivElement, EditorContentProps>(
  ({ className, children, initialContent, ...rest }, ref) => (
    <div ref={ref} className={className}>
      <EditorProvider {...rest} content={initialContent}>
        {children}
      </EditorProvider>
    </div>
  ),
);

EditorContent.displayName = "EditorContent";
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `className` | `string` | no | `undefined` | Applied to the wrapping `<div>` |
| `initialContent` | `JSONContent` | no | `undefined` | Initial document passed as `content` to `EditorProvider`. `JSONContent` (re-exported from `@tiptap/react`) is `{ type?: string; attrs?: Record<string, any>; content?: JSONContent[]; marks?: { type: string; attrs?: Record<string, any> }[]; text?: string; [key: string]: any }` |
| `children` | `ReactNode` | no | — | React nodes rendered inside `EditorProvider` (e.g. `EditorCommand`, `EditorBubble`) |
| `extensions` | `Extensions` (Tiptap) | no | — | Passed through to `EditorProvider`; `Array<AnyExtension>` |
| `editorProps` | `EditorProps` (Tiptap) | no | — | Passed through, e.g. `{ handlePaste, handleDrop, handleDOMEvents, attributes }` |
| `onUpdate`, `onSelectionUpdate`, `slotAfter`, ... | inherited from `EditorProviderProps` minus `content` | no | — | Any other `@tiptap/react` `EditorProvider` prop is forwarded verbatim through `...rest` |

`EditorProviderProps` is the `@tiptap/react` type (from `@tiptap/react`, not defined in this repo); everything on it except `content` is accepted.

**Returns:** `forwardRef` component; ref is attached to the wrapping `<div>`. `forwardRef<HTMLDivElement, EditorContentProps>`.

Throws/rejects: none synchronously; errors surface as Tiptap exceptions during render/update (not documented upstream here).

### Usage — basic
```tsx
import { EditorRoot, EditorContent } from "novel";
import StarterKit from "@tiptap/starter-kit";

export function App() {
  return (
    <EditorRoot>
      <EditorContent
        initialContent={{ type: "doc", content: [{ type: "paragraph", content: "Hello" }] }}
        extensions={[StarterKit]}
      />
    </EditorRoot>
  );
}
```

### Usage — save-on-update with localStorage persistence
```tsx
import { useCallback, useRef } from "react";
import { EditorRoot, EditorContent, type EditorInstance } from "novel";
import { useDebouncedCallback } from "use-debounce";

export function PersistedEditor() {
  const save = useDebouncedCallback((editor: EditorInstance) => {
    window.localStorage.setItem("doc", JSON.stringify(editor.getJSON()));
  }, 500);

  return (
    <EditorRoot>
      <EditorContent
        editorProps={{
          attributes: { class: "prose focus:outline-none" },
          handleDOMEvents: {
            keydown: (_view, event) => {
              if (["ArrowUp", "ArrowDown", "Enter"].includes(event.key)) return true;
              return false;
            },
          },
        }}
        onUpdate={({ editor }) => save(editor)}
        slotAfter={null}
      />
    </EditorRoot>
  );
}
```

### Related
- `useEditor` (alias of `useCurrentEditor`, `@tiptap/react`) — inside an `EditorContent`, returns `{ editor }`; components must handle the `!editor` case (the built-in components return `null`).
- `type EditorInstance` — alias of `Editor` from `@tiptap/core`; its `getJSON()`, `getHTML()`, `chain()`, `state`, `storage.markdown` APIs are used throughout this reference.
- `EditorCommand` requires the tunnel established by `EditorRoot` — see [editor-command.md](editor-command.md).
```

--------------------------------

### getPrevText

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/markdown-utils.md

Returns the markdown content before a given position in the editor document. Requires the MarkdownExtension to be installed.

```APIDOC
## getPrevText

### Description
Returns the markdown content before a given position in the editor document. Requires the MarkdownExtension to be installed.

### Method
Function

### Signature
`(editor: EditorInstance, position: number) => string`

### Parameters
- `editor` (EditorInstance) - Required - The editor instance from `@tiptap/core`; requires the `MarkdownExtension` in the extension list.
- `position` (number) - Required - Document position (e.g. `editor.state.selection.from`); only nodes before this position are included.

### Returns
`string` - The content before `position`, serialized to markdown via `editor.storage.markdown.serializer.serialize(doc)`.

### Throws
No explicit throwing path, but reading `editor.storage.markdown` throws/breaks at runtime if the `MarkdownExtension` is not installed.

### Usage - basic
```ts
import { getPrevText, useEditor } from "novel";

const { editor } = useEditor();
const context = getPrevText(editor, editor.state.selection.from);
```

### Usage - AI "continue writing" (as in `AISelectorCommands`)
```tsx
import { getPrevText, useEditor } from "novel";

const { editor } = useEditor();

function continueWriting() {
  const pos = editor.state.selection.from;
  const text = getPrevText(editor, pos);
  // send `text` to your AI completion endpoint as the prompt
  complete(text, { body: { option: "continue" } });
}
```
```

--------------------------------

### Extension Configurations

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/configuration.md

Configuration for bundled Tiptap extensions used in the reference app.

```APIDOC
## Extension Configurations

### Description
Configuration for bundled Tiptap extensions used in the reference app.

### Parameters
#### Request Body
- **StarterKit** (object) - Required - HTMLAttributes per node (bulletList, orderedList, listItem, blockquote, codeBlock, code), horizontalRule: false, dropcursor: { color: "#DBEAFE", width: 4 }, gapcursor: false
- **TiptapLink** (object) - Required - HTMLAttributes.class styled link classes
- **TiptapImage** (object) - Required - extended with UploadImagesPlugin, .configure({ allowBase64: true, HTMLAttributes.class })
- **UpdatedImage** (object) - Required - .configure({ HTMLAttributes.class })
- **TaskList** / **TaskItem** (object) - Required - Tailwind classes; TaskItem { nested: true }
- **HorizontalRule** (object) - Required - Tailwind classes
- **CodeBlockLowlight** (object) - Required - { lowlight: createLowlight(common) } (37 grammars)
- **Youtube** (object) - Required - { HTMLAttributes.class, inline: false }
- **Twitter** (object) - Required - { HTMLAttributes: { class: "not-prose" }, inline: false }
- **Mathematics** (object) - Required - { HTMLAttributes: { class: "..." }, katexOptions: { throwOnError: false } }
- **MarkdownExtension** (object) - Required - { html: true, tightLists: true, tightListClass: "tight", bulletListMarker: "-", linkify: false, breaks: false, transformPastedText: false, transformCopiedText: false } — differs from the package default (html: false, transformCopiedText: true)
```

--------------------------------

### Error handling patterns for editor commands, image upload, and completions

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/errors.md

Four error-handling patterns in a Novel app: check the boolean returned by editor.chain().setTweet().run() , handle the onUpload promise rejection in createImageUpload, inspect the response status with useCompletion, and guard against null editor with an early return. Includes a note that the only throwing code in packages/headless/src is in lazy branches, never executed synchronously.

```ts
// 1. Command aborts: check the boolean returned by the chain
const ok = editor.chain().setTweet({ src }).run(); // false → invalid URL; validate first:
if (!isValidTwitterUrl(src)) {
  // show your own validation UI
}

// 2. Upload rejections: handle the promise inside onUpload
const uploadFn = createImageUpload({
  onUpload: (file) =>
    fetch("/api/upload", { method: "POST", body: file }).then(async (res) => {
      if (res.status === 200) return ((await res.json()) as { url: string }).url;
      throw new Error("upload failed");
    })
    .catch((e) => {
      toast.error(e.message);
      throw e; // surface to the plugin's reject handler
    }),
});

// 3. Endpoint errors: check response status client-side
const { completion, complete } = useCompletion({
  api: "/api/generate",
  onResponse: (res) => { if (res.status === 429) toast.error("Rate limited"); },
  onError: (e) => toast.error(e.message),
});

// 4. Null-render components: no try/catch needed; guard JSX visibility if required
if (!editor) return null; // standard pattern before using commands
```

--------------------------------

### Image upload with validation and 401 fallback using createImageUpload

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/plugins-upload-images.md

This snippet from `apps/web/components/tailwind/image-upload.ts` shows how to configure `createImageUpload` with an `onUpload` callback that posts the file to `/api/upload` and handles success, 401 (fallback to local data-URL), and other errors. It also includes a `validateFn` that checks the file type (must be an image) and size (max 20MB). The 401 fallback resolves with the original file, allowing the editor to display a local preview.

```typescript
import { createImageUpload } from "novel";
import { toast } from "sonner";

export const uploadFn = createImageUpload({
  onUpload: (file) => {
    const promise = fetch("/api/upload", {
      method: "POST",
      headers: { "content-type": file?.type || "application/octet-stream", "x-vercel-filename": file?.name || "image.png" },
      body: file,
    });
    return new Promise((resolve, reject) => {
      toast.promise(promise.then(async (res) => {
        if (res.status === 200) {
          const { url } = (await res.json()) as { url: string };
          const image = new Image();
          image.src = url;
          image.onload = () => resolve(url);
        } else if (res.status === 401) {
          resolve(file); // fall back to local data-URL
          throw new Error("`BLOB_READ_WRITE_TOKEN` environment variable not found, reading image locally instead.");
        } else {
          throw new Error("Error uploading image. Please try again.");
        }
      }), {
        loading: "Uploading image...",
        success: "Image uploaded successfully.",
        error: (e) => { reject(e); return e.message; },
      });
    });
  },
  validateFn: (file) => {
    if (!file.type.includes("image/")) { toast.error("File type not supported."); return false; }
    if (file.size / 1024 / 1024 > 20) { toast.error("File size too big (max 20MB)."); return false; }
    return true;
  },
});
```

--------------------------------

### Math nodes in JSON content

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/extensions-mathematics.md

Shows how math nodes are serialized in JSON content, with type "math" and attrs.latex. This example is from the defaultEditorContent in apps/web/lib/content.ts.

```ts
{
  type: "orderedList",
  attrs: { tight: true, start: 1 },
  content: [
    { type: "listItem", content: [{ type: "paragraph", content: [{ type: "math", attrs: { latex: "E = mc^2" } }] }] },
    { type: "listItem", content: [{ type: "paragraph", content: [{ type: "math", attrs: { latex: "\\sum_{i=0}^n x_i" } }] }] },
  ],
}
```

--------------------------------

### JSON content for a tweet node

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/extensions-twitter.md

Example JSON content representing a tweet node with its source URL attribute. This is the structure used when inserting a tweet into the document content.

```ts
{
  type: "twitter",
  attrs: { src: "https://x.com/elonmusk/status/1800759252224729577" },
}
```

--------------------------------

### Basic usage of Novel extensions

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/extensions-bundled.md

Imports and configures a set of Novel extensions for a basic editor. The TiptapLink extension is configured with openOnClick: false.

```tsx
import {
  EditorContent, Placeholder, StarterKit, TiptapLink,
  TiptapUnderline, TextStyle, Color, CustomKeymap, MarkdownExtension,
} from "novel";

<EditorContent
  extensions={[
    StarterKit, Placeholder, TiptapLink.configure({ openOnClick: false }),
    TiptapUnderline, TextStyle, Color, CustomKeymap, MarkdownExtension,
  ]}
/>;
```

--------------------------------

### Basic EditorContent usage

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/editor-root-and-content.md

Basic usage of EditorContent inside EditorRoot. Sets initialContent as a JSON document and passes the StarterKit extension. Requires importing EditorRoot and EditorContent from 'novel'.

```tsx
import { EditorRoot, EditorContent } from "novel";
import StarterKit from "@tiptap/starter-kit";

export function App() {
  return (
    <EditorRoot>
      <EditorContent
        initialContent={{ type: "doc", content: [{ type: "paragraph", content: "Hello" }] }}
        extensions={[StarterKit]}
      />
    </EditorRoot>
  );
}
```

--------------------------------

### Wiring uploadFn into EditorContent

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/plugins-upload-images.md

Shows how to pass the upload function to the editor's handlePaste and handleDrop props.

```tsx
<EditorContent
  editorProps={{
    handlePaste: (view, event) => handleImagePaste(view, event, uploadFn),
    handleDrop: (view, event, _slice, moved) => handleImageDrop(view, event, moved, uploadFn),
  }}
/>
```

--------------------------------

### renderItems function

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/extensions-slash-command.md

Returns a @tiptap/suggestion renderer object. The onStart callback mounts EditorCommandOut via ReactRenderer and returns false when the caret is inside a codeBlock. onKeyDown handles Escape and forwards other keys to the cmdk component.

```ts
const renderItems = (elementRef?: RefObject<Element> | null) => {
  let component: ReactRenderer | null = null;
  let popup: Instance<Props>[] | null = null;

  return {
    onStart: (props: { editor: Editor; clientRect: DOMRect }) => {
      component = new ReactRenderer(EditorCommandOut, {
        props,
        editor: props.editor,
      });

      const { selection } = props.editor.state;
      const parentNode = selection.$from.node(selection.$from.depth);
      const blockType = parentNode.type.name;

      if (blockType === "codeBlock") {
        return false;
      }

      popup = tippy("body", {
        getReferenceClientRect: props.clientRect,
        appendTo: () => (elementRef ? elementRef.current : document.body),
        content: component.element,
        showOnCreate: true,
        interactive: true,
        trigger: "manual",
        placement: "bottom-start",
      });
    },
    onUpdate: (props: { editor: Editor; clientRect: GetReferenceClientRect }) => {
      component?.updateProps(props);
      popup?.[0]?.setProps({ getReferenceClientRect: props.clientRect });
    },
    onKeyDown: (props: { event: KeyboardEvent }) => {
      if (props.event.key === "Escape") {
        popup?.[0]?.hide();
        return true;
      }
      return component?.ref?.onKeyDown(props);
    },
    onExit: () => {
      popup?.[0]?.destroy();
      component?.destroy();
    },
  };
};
```

--------------------------------

### renderItems

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/extensions-slash-command.md

Factory function that returns a @tiptap/suggestion renderer object with onStart, onUpdate, onKeyDown, and onExit callbacks. Used to mount the command palette popup.

```APIDOC
## renderItems

### Description
Creates a renderer object for @tiptap/suggestion. The returned object handles mounting, updating, keyboard events, and cleanup of the command palette popup.

### Signature
ts
const renderItems = (elementRef?: RefObject<Element> | null) => {
  // ...
};


### Parameters
- **elementRef** (RefObject<Element> | null) - Optional - Default: `null` - Element to append the tippy popup to (`appendTo`); defaults to `document.body`

### Returns
An object with the following callbacks:

- **onStart** - `({ editor: Editor; clientRect: DOMRect }) => boolean | void` - Mounts `EditorCommandOut` via `ReactRenderer` (this is the tunnel outlet that renders the `EditorCommand` palette). Returns `false` (suggestion not shown) when the caret is inside a `codeBlock`
- **onUpdate** - `({ editor: Editor; clientRect: GetReferenceClientRect }) => void` - Updates renderer props and repositions the popup
- **onKeyDown** - `({ event: KeyboardEvent }) => boolean` - `Escape` hides the popup and returns `true`; otherwise forwards to the cmdk component's ref (`component?.ref?.onKeyDown(props)`)
- **onExit** - `() => void` - Destroys popup and renderer

### Usage — basic
tsx
import { renderItems } from "novel";

Command.configure({
  suggestion: {
    items: () => items,
    render: renderItems, // popup appended to document.body
  },
});

// or constrain the popup to a container:
Command.configure({
  suggestion: {
    items: () => items,
    render: renderItems(containerRef),
  },
});

```

--------------------------------

### handleImagePaste function

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/plugins-upload-images.md

Handles paste events for images. Returns true if clipboard contains files, preventing default paste and starting upload; otherwise returns false. Use as Tiptap editorProps.handlePaste.

```ts
export const handleImagePaste = (view: EditorView, event: ClipboardEvent, uploadFn: UploadFn) => {
  if (event.clipboardData?.files.length) {
    event.preventDefault();
    const [file] = Array.from(event.clipboardData.files);
    const pos = view.state.selection.from;

    if (file) uploadFn(file, view, pos);
    return true;
  }
  return false;
};
```

--------------------------------

### getUrlFromString usage in link creation form

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/markdown-utils.md

Example from the reference app's LinkSelector component. Uses getUrlFromString to allow users to paste bare domains, then sets a link in the editor if a valid URL is obtained.

```tsx
import { getUrlFromString, useEditor } from "novel";

const { editor } = useEditor();
const url = getUrlFromString(inputValue);
if (url) {
  editor.chain().focus().setLink({ href: url }).run();
}
```

--------------------------------

### Configure HighlightExtension

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/extensions-bundled.md

Configures the Tiptap Highlight extension with multicolor enabled. Re-exported as HighlightExtension, allowing multiple highlight colors via toggleHighlight({ color: ... }).

```typescript
const HighlightExtension = Highlight.configure({
  multicolor: true,
});
```

--------------------------------

### Usage: removeAIHighlight on close toggle

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/extensions-ai-highlight.md

Example usage of `removeAIHighlight`. It calls the function when the `open` state becomes falsy, using `useEffect` to react to the change. The comment notes this is used in the reference app's `GenerativeMenuSwitch`.

```tsx
import { removeAIHighlight, useEditor } from "novel";

useEffect(() => {
  if (!open) removeAIHighlight(editor);
}, [open]); // as in the reference app's GenerativeMenuSwitch

```

--------------------------------

### Configure Placeholder extension

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/extensions-bundled.md

Configures the Tiptap Placeholder extension with per-node placeholder text: 'Heading {level}' for headings, otherwise 'Press / for commands'. Sets includeChildren to true. Re-exported as Placeholder.

```typescript
const PlaceholderExtension = Placeholder.configure({
  placeholder: ({ node }) => {
    if (node.type.name === "heading") {
      return `Heading ${node.attrs.level}`;
    }
    return "Press '/' for commands";
  },
  includeChildren: true,
});
```

--------------------------------

### EditorBubbleItem using editor argument in handler

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/editor-bubble.md

Use this to create a delete button that removes the current selection. The `onSelect` callback receives the editor instance and uses `editor.state.selection` to get the range, then calls `deleteRange` to remove it.

```tsx
import { EditorBubble, EditorBubbleItem } from "novel";

export const DeleteBar = () => (
  <EditorBubble>
    <EditorBubbleItem
      onSelect={(editor) => {
        const { from, to } = editor.state.selection;
        editor.chain().focus().deleteRange({ from, to }).run();
      }}
    >
      Delete selection
    </EditorBubbleItem>
  </EditorBubble>
);
```

--------------------------------

### Custom HorizontalRule extension with input rules

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/extensions-bundled.md

Extends the Tiptap HorizontalRule extension with additional input rules. Typing '---', '—-', '___' (space), or '***' (space) at line start inserts a horizontal rule. Re-exported as HorizontalRule.

```typescript
const Horizontal = HorizontalRule.extend({
  addInputRules() {
    return [
      new InputRule({
        find: /^(?:---|—-|___\s|\*\*\*\s)$/u,
        handler: ({ state, range }) => {
          const attributes = {};

          const { tr } = state;
          const start = range.from;
          const end = range.to;

          tr.insert(start - 1, this.type.create(attributes)).delete(tr.mapping.map(start), tr.mapping.map(end));
        },
      }),
    ];
  },
});
```

--------------------------------

### Basic usage of Mathematics extension

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/extensions-mathematics.md

Shows how to import and use the Mathematics extension in a React component. Includes creating a math node from a selection with setLatex and converting it back to plain text with unsetLatex.

```tsx
import { Mathematics, EditorContent } from "novel";
import "katex/dist/katex.min.css";

<EditorContent extensions={[Mathematics]} />;

// create a math node from a selection:
editor.chain().focus().setLatex({ latex: "E = mc^2" }).run();

// back to plain text:
editor.chain().focus().unsetLatex().run();
```

--------------------------------

### addAIHighlight

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/extensions-ai-highlight.md

Imperative helper that highlights the current selection while the user composes an AI prompt.

```APIDOC
## addAIHighlight

### Description
Imperative helper that highlights the current selection while the user composes an AI prompt.

### Method
Function

### Parameters
- **editor** (Editor) - Required - The Tiptap editor instance.

### Usage Example
ts
import { addAIHighlight, useEditor } from "novel";
const { editor } = useEditor();
addAIHighlight(editor);


### Returns
No return value.
```

--------------------------------

### AIHighlightOptions

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/types.md

Options for the AIHighlight extension.

```APIDOC
## AIHighlightOptions

### Description
Options for the AIHighlight extension.

### Fields

| Field | Type | Required | Description |
|---|---|---|---|
| `HTMLAttributes` | `Record<string, string>` | yes | Merged onto rendered `<mark>` |

### Accepted by
`AIHighlight` (`Mark.create<AIHighlightOptions>`).
```

--------------------------------

### handleImageDrop function

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/plugins-upload-images.md

Handles drop events for images. Returns true if an un-moved drop with files is handled, using view.posAtCoords to find position and deducting 1 to avoid extra node. Drops starting inside the editor (moved === true) are ignored.

```ts
export const handleImageDrop = (view: EditorView, event: DragEvent, moved: boolean, uploadFn: UploadFn) => {
  if (!moved && event.dataTransfer?.files.length) {
    event.preventDefault();
    const [file] = Array.from(event.dataTransfer.files);
    const coordinates = view.posAtCoords({
      left: event.clientX,
      top: event.clientY,
    });
    // here we deduct 1 from the pos or else the image will create an extra node
    if (file) uploadFn(file, view, coordinates?.pos ?? 0 - 1);
    return true;
  }
  return false;
};
```

--------------------------------

### queryAtom

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/editor-command.md

Jotai atom holding the current cmdk search query string.

```APIDOC
## queryAtom

### Description
Current cmdk search query, set by `EditorCommandOut`.

### Type
`PrimitiveAtom<string>`

### Source
`packages/headless/src/utils/atoms.ts`

### Usage
```ts
import { queryAtom } from "novel";
```
```

--------------------------------

### Basic EditorRoot and EditorContent usage

Source: https://github.com/steven-tey/novel/blob/main/_autodocs/api-reference/editor-root-and-content.md

Basic usage of EditorRoot and EditorContent. EditorRoot must wrap EditorContent. The initialContent prop is set to a document with a single paragraph.

```tsx
import { EditorRoot, EditorContent } from "novel";

export function App() {
  return (
    <EditorRoot>
      <EditorContent initialContent={{ type: "doc", content: [{ type: "paragraph" }] }} />
    </EditorRoot>
  );
}
```
Tokens:
Raw