Components overview

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/devscribe-team/webeditor/llms.txt

Use this file to discover all available pages before exploring further.

​

Introduction

​

Architecture

1. A ProseMirror Node: Defined with a NodeSpec that specifies its structure, attributes, and parsing rules
2. A React NodeView: Rendered as a React component with full access to React hooks and state
3. Insertable via Commands: Accessible through the command menu with keyboard shortcuts
4. Serializable: Can be converted to/from HTML for persistence

​

Component lifecycle

// 1. Node specification defines the schema
export const cardNodeSpec: NodeSpec = {
  group: "block",
  content: "block*",
  attrs: {
    title: { default: "Card Title" },
    icon: { default: null },
    showIcon: { default: true },
    horizontal: { default: false },
    href: { default: null },
  },
  // ... parsing and serialization rules
};

// 2. React component renders the node
export const CardNodeView = React.forwardRef<HTMLDivElement, NodeViewComponentProps>(
  ({ nodeProps, ...props }, ref) => {
    // Component implementation
  }
);

// 3. Insert function for programmatic insertion
export function insertCard(state: EditorState): Transaction {
  // Creates and inserts the card node
}

​

Available components

​

Block components

<card title="Card Title" icon="FileText" show-icon="true">
  <p>Card content goes here</p>
</card>

​

Inline components

<badge variant="default" label="New Feature" />

​

Component categories

​

Content containers

• Card: Display content in a styled card with optional icon and title
• Callout: Highlight important information with contextual styling (info, warning, caution, tip, important)
• Accordion: Create collapsible sections for better content organization
• Tabs: Organize content into switchable tabs
• Field: Display form-like fields with labels and descriptions
• Columns: Create multi-column layouts

​

Code and diagrams

• Code Snippet: Syntax-highlighted code blocks with language support (JavaScript, TypeScript, Python, Rust, SQL, CSS, HTML)
• Mermaid: Render flowcharts, diagrams, and graphs using Mermaid syntax

​

Media and embeds

• Frame: Embed external content via iframe with configurable dimensions

​

Visual elements

• Badge: Inline status indicators or labels with variant styles (default, secondary, destructive, outline)
• Icon: Display Lucide icons inline with customizable size
• Break: Visual separator or spacer
• Steps: Numbered step-by-step instructions

​

Component attributes

​

Card attributes

​

Callout attributes

​

Code snippet attributes

​

Badge attributes

​

Using components

​

Via command menu

1. Place cursor in an empty paragraph
2. Press / to open the command menu
3. Type to search for a component
4. Select with arrow keys and press Enter
5. Configure component attributes in the modal (if applicable)

​

Via markdown syntax

<card title="My Card">
  Content here
</card>

​

Programmatically

import { insertCard, insertCallout } from '@devscribe-team/webeditor';

// In a ProseMirror command
function myCommand(state: EditorState, dispatch?: (tr: Transaction) => void) {
  const tr = insertCard(state);
  if (dispatch) dispatch(tr);
  return true;
}

​

Editing components

• Clicking: Click on component titles, icons, or attributes to open edit modals
• Keyboard: Use Tab to focus components, Enter/Space to edit
• Hover options: Some components show additional options on hover (e.g., Card layout toggle)

​

Edit modals

• Title/Description modals: Edit text content
• Icon modals: Search and select Lucide icons
• Type modals: Change component variants (e.g., Callout type)
• Code modals: Edit code with syntax highlighting

​

Component styling

​

Theme-aware components

// Light mode: light backgrounds, dark text
// Dark mode: dark backgrounds, light text

​

Customization

1. CSS variables: Override Tailwind theme variables
2. Tailwind config: Extend the default theme
3. Custom styles: Add additional CSS classes

​

Creating custom components

1. Define a NodeSpec with the component schema
2. Create a React NodeView component
3. Add parsing rules for HTML/markdown
4. Register the component in the editor schema
5. Add an insert function and command

// 1. Define node spec
export const myComponentSpec: NodeSpec = {
  group: "block",
  content: "block+",
  attrs: {
    title: { default: "Default Title" },
  },
  parseDOM: [{
    tag: "my-component",
    getAttrs: (dom) => ({
      title: dom.getAttribute("title") || "Default Title",
    }),
  }],
  toDOM: (node) => [
    "my-component",
    { title: node.attrs.title },
    0,
  ],
};

// 2. Create React NodeView
export const MyComponentNodeView = React.forwardRef<
  HTMLDivElement,
  NodeViewComponentProps
>(({ nodeProps, ...props }, ref) => {
  const title = nodeProps.node.attrs.title;
  
  return (
    <div ref={ref} {...props}>
      <h3>{title}</h3>
      <div>{/* Content */}</div>
    </div>
  );
});

// 3. Create insert function
export function insertMyComponent(state: EditorState): Transaction {
  const node = state.schema.nodes.my_component.create(
    { title: "Default Title" },
    state.schema.nodes.paragraph.create()
  );
  
  let tr = state.tr.replaceSelectionWith(node);
  return tr;
}

​

Best practices

​

Performance tips

1. Lazy load icons: The dynamic icon loader caches loaded icons
2. Memoize render: Use React.memo for expensive components
3. Avoid re-renders: Use contentEditable={false} for non-editable parts
4. Optimize modals: Only render modals when open

​

See also

• WebEditor - Main editor component documentation
• useTheme Hook - Theme management
• Quickstart - Get started with WebEditor