Tiptap Extensions

A collection of extensions for Tiptap, including step-by-step guides and disclosures.

Getting Started

Installation

npm install @namesake/tiptap-extensions

Steps

To use steps, import StepsKit from @namesake/tiptap-extensions.

In order to insert and use steps, one or more nodes within your document need to accept the "steps" content type.

import { StepsKit } from "@namesake/tiptap-extensions";
import Document from "@tiptap/extension-document";
import { useEditor, EditorContent } from "@tiptap/react";
import StarterKit from "@tiptap/starter-kit";

const Editor = () => {
  const editor = useEditor({
    extensions: [
      StarterKit.configure({
        document: false,
      }),
      Document.extend({
        // Change from "block+" (default)
        content: "(block | steps)+", 
      }),
      // Pass in the steps extensions
      StepsKit
    ],
    content: "Hello world",
  });

  return <EditorContent editor={editor} />;
};

export default Editor;

Styling

If you want the steps to look like the example, add this CSS to your app:

ol[data-type="steps"] {
  counter-reset: steps;
  display: flex;
  flex-direction: column;

  &:not(:first-child) {
    margin-top: 1.5rem;
  }
}

li[data-type="step-item"] {
  padding: 0;
  counter-increment: steps;
  display: grid;
  column-gap: 1rem;
  grid-template-columns: 32px 1fr;
  grid-template-rows: auto 1fr;
  grid-template-areas:
    "number title"
    "line content";

  &::before {
    all: unset;
    width: 100%;
    aspect-ratio: 1;
    display: flex;
    align-items: center;
    justify-content: center;
    border-radius: 50%;
    grid-area: number;
    content: counter(steps);
    background-color: #00000017;
  }

  &::after {
    grid-area: line;
    width: 2px;
    height: 100%;
    margin-inline: auto;
    background-color: #0000000F;
    content: "";
  }

  &:last-child::after {
    visibility: hidden;
  }

  &:last-child div[data-type="step-content"] {
    padding-bottom: 0.75rem;
  }
}

div[data-type="step-title"] {
  grid-area: title;
  font-size: 2rem;
  font-weight: medium;
}

div[data-type="step-content"] {
  grid-area: content;
  padding-block-end: 1.5rem;
}

Placeholders

If you want to display placeholder text for the title or description, add the Tiptap Placeholder extension:

npm install @tiptap/extension-placeholder

Then add it to your editor config:

import Placeholder from "@tiptap/extension-placeholder";

const Editor = () => {
  const editor = useEditor({
    extensions: [
      // ...other document extensions
      Placeholder.configure({
        includeChildren: true,
        showOnlyCurrent: false, 
        placeholder: ({ node }) => {
          // Return different placeholders depending on node type
          if (node.type.name === "stepTitle") {
            return "Add a title…";
          }
    
          if (node.type.name === "stepContent") {
            return "Add instructions…";
          }
    
          return "Write something…";
        },
      }),
      // Pass in the steps extensions
      StepsKit
    ]
  });

  return <EditorContent editor={editor} />;
};

export default Editor;

The placeholder is unstyled by default, so be sure to add CSS styles:

div[data-type='step-title'].is-empty::before,
div[data-type='step-content'].is-empty::before {
  content: attr(data-placeholder);
  color: #00000050;
  float: left;
  height: 0;
  pointer-events: none;
}

Read more about the Tiptap placeholder extension.

Commands

Just as with other Tiptap extensions, the Steps extension comes with commands that you can chain together when working within Tiptap.

| Command | Description | Keyboard Shortcut | |---------|-------------|-------------------| | toggleSteps | Toggles between steps and text content. When inside a steps list, removes selected steps. When outside, creates new steps from selected content. | Cmd/Ctrl-Alt-s | | insertStep | Insert a new step. Accepts options: { title?: string; content?: JSONContent[]; before?: boolean }. If before is true, inserts before the current step; otherwise, inserts after. | - | | removeStep | Remove the current step, converting its content to regular text. Preserves the step's title as a heading if present. | - |

These commands can be used to create toolbar buttons which toggle the state of the steps component on or off.

editor.chain().focus().toggleSteps().run()

Disclosures

To use disclosures, import DisclosuresKit from @namesake/tiptap-extensions.

import { DisclosuresKit } from "@namesake/tiptap-extensions";
import Document from "@tiptap/extension-document";
import { useEditor, EditorContent } from "@tiptap/react";
import StarterKit from "@tiptap/starter-kit";

const Editor = () => {
  const editor = useEditor({
    extensions: [
      StarterKit,
      DisclosuresKit
    ],
    content: "Hello world",
  });

  return <EditorContent editor={editor} />;
};

export default Editor;

Commands

Just as with other Tiptap extensions, the Disclosure extension comes with commands that you can chain together when working within Tiptap.

| Command | Description | Keyboard Shortcut | |---------|-------------|-------------------| | toggleDisclosures | Toggles between a disclosure and text content. When inside a disclosure group, removes selected disclosure items. When outside, creates new disclosure items from selected content. | Cmd/Ctrl-Alt-d | | insertDisclosure | Insert a new disclosure item. Accepts options: { title?: string; content?: JSONContent[]; before?: boolean }. If before is true, inserts before the current step; otherwise, inserts after. | - | | removeDisclosure | Remove the current disclosure item, converting its content to regular text. Preserves the disclosure's title as a heading if present. | - |

These commands can be used to create toolbar buttons which toggle the state of the disclosure component on or off.

editor.chain().focus().toggleDisclosures().run()