structiq

A rich text editor built on TipTap, designed for React applications. Supports slash commands, tables, image insertion, custom translations, and flexible layout control — all configurable through props.

Installation

npm install structiq
# or
yarn add structiq
# or
pnpm add structiq

Requirements: React 18+, Tailwind CSS

Basic Usage

import { useState } from "react";
import { StructiqEditor } from "structiq";
import "structiq/dist/index.css";

function App() {
  const [content, setContent] = useState("");

  return (
    <StructiqEditor
      content={content}
      onChange={(html) => setContent(html)}
      onBlur={(html) => console.log("Saved:", html)}
      autoFocus
    />
  );
}

Props

Core

| Prop | Type | Default | Description | | ----------- | ------------------------ | ------- | ------------------------------------------------------------ | | content | string | "" | HTML content to display in the editor | | onChange | (html: string) => void | — | Called whenever the content changes | | onBlur | (html: string) => void | — | Called when the editor loses focus (only if content changed) | | autoFocus | boolean | false | Focus the editor on mount | | disabled | boolean | false | Makes the editor read-only | | className | string | — | Additional CSS classes applied to the editor |

Layout

| Prop | Type | Default | Description | | -------------- | -------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------- | | height | "auto" \| "full" \| number \| string | "auto" | Sets the editor height. "full" fills the parent container. Numbers are treated as px. | | minHeight | number \| string | — | Minimum height. Numbers are treated as px. | | maxHeight | number \| string | — | Maximum height. Enables vertical scrolling when content exceeds this value. Numbers are treated as px. | | customHeight | boolean | false | Enables internal scroll behavior when using a fixed height. |

// Fixed height with scroll
<StructiqEditor height={400} customHeight />

// Min/max bounds
<StructiqEditor minHeight={200} maxHeight={600} />

// Fill parent container
<StructiqEditor height="full" />

Feature Flags

| Prop | Type | Default | Description | | -------------- | --------- | ------- | ------------------------------------------------------------------- | | enableIndent | boolean | false | Enables Tab / Shift+Tab indentation for paragraphs and headings | | enableImages | boolean | false | Enables image insertion. Supports Base64 encoded images. |

Translations

The translations prop lets you override placeholder text shown inside the editor. Useful for internationalization or customizing the default hints.

<StructiqEditor
  translations={{
    paragraph: "Start typing...",
    heading: (level) => `Heading ${level}`,
    listItem: "Add a list item",
    orderedList: "Add a numbered item",
    blockquote: "Add a quote",
    codeBlock: "Write your code here...",
    link: "Paste a URL",
    default: "",
  }}
/>

| Key | Type | Default value | | ------------- | --------------------------- | ----------------------------------- | | paragraph | string | "Type / for commands" | | heading | (level: number) => string | (level) => `Heading ${level}` | | listItem | string | "List" | | orderedList | string | "Numbered list" | | blockquote | string | "Quote" | | codeBlock | string | "Write code…" | | link | string | "Paste a link" | | default | string | "" |

Only the keys you provide are overridden — the rest use their defaults.

Slash Commands

The editor includes a built-in set of slash commands triggered by typing /. You can extend or fully replace them using the slashCommands prop.

| Prop | Type | Default | Description | | -------------------- | ---------------- | -------------------------------------- | ------------------------------------------------- | | slashCommands | SlashCommand[] | Built-in defaults | Replaces or extends the slash command list | | slashMenuClassName | string | "max-h-[320px] kt-scrollable-y-auto" | CSS classes applied to the slash command dropdown |

import { StructiqEditor, SlashCommand } from "structiq";

const customCommands: SlashCommand[] = [
  {
    id: "my-block",
    title: "My Block",
    description: "Insert a custom block",
    execute: (editor) => {
      // use TipTap editor commands here
    },
  },
];

// Full override — replaces all built-in commands
<StructiqEditor slashCommands={customCommands} />;

// Partial override — spread defaults and replace or append
import { defaultSlashCommands } from "structiq";

<StructiqEditor slashCommands={[...defaultSlashCommands, ...customCommands]} />;

To style the dropdown:

<StructiqEditor slashMenuClassName="max-h-[400px] overflow-y-auto shadow-lg" />

Emojis

The emojis prop lets you append custom emoji entries to the built-in emoji list available in the slash menu.

| Prop | Type | Default | Description | | -------- | --------------------- | ------- | ------------------------------------------ | | emojis | { value: string }[] | — | Additional emojis merged with the defaults |

<StructiqEditor emojis={[{ value: "🚀" }, { value: "🎯" }, { value: "🧠" }]} />

Behavior Notes

onChange fires only when the content has actually changed from its last saved state. It does not fire on initial render.

onBlur triggers only when the editor loses focus and the content is dirty (modified since last save). If the content is unchanged, onBlur is suppressed.

Empty content is normalized to an empty string "". Tiptap's internal empty representations (<p></p>, <p><br></p>) are collapsed automatically.

autoFocus places the cursor at the start if the editor is empty, or at the end if it already has content.

External content updates are synced into the editor when the content prop changes, but only if the text content has actually changed — preventing unnecessary re-renders from parent state updates.

Styling

Import the package stylesheet once at the root of your application:

import "structiq/dist/index.css";

The editor supports dark mode out of the box. Dark mode styles are applied automatically via Tailwind's dark: variants when your application has dark mode enabled.

You can pass additional classes to the editor surface via the className prop:

<StructiqEditor className="rounded-xl border-2 border-blue-500" />

TypeScript

The package is fully typed. The SlashCommand type is exported for use when building custom command arrays:

import type { SlashCommand, PlaceholderTranslations } from "structiq";

License

MIT