# Eddyter — API Reference & Integration Guide

> Eddyter is a plug-and-play, AI-native rich text editor built on Meta's Lexical framework. Drop it into any React application in about 10 minutes — without managing infrastructure, storage, or AI.

**Compatibility:** React 18.2+ and React 19.x. Works with Next.js (App & Pages Router), Vite, Create React App, and any Webpack-based React framework.

**Stack:** React, Next.js, TypeScript. Built on Meta's Lexical framework.

---

## Pricing & Plans

Eddyter offers five tiers designed to scale from side projects to production SaaS applications.

| Plan | Price | Storage | API Keys | What's Included |
|---|---|---|---|---|
| **Free** | $0/month | — | — | Core rich text editor for evaluation and personal projects. Eddyter branding in footer. |
| **Starter** | $12/month | 1 GB | 1 | 3,000 editor loads per month, core rich text editing, secure media uploads, stable editor infrastructure, community support. Powered-by-Eddyter branding. Best for side projects and early-stage products. |
| **Pro** | $29/month | 2 GB | 3 | Everything in Starter plus premium toolbar options, advanced table features, priority support, no Eddyter branding. |
| **AI Pro (BYOK)** | $39/month | 3 GB | 4 | Everything in Pro plus AI features powered by your own API key (Bring Your Own Key). You provide your OpenAI/Anthropic key; Eddyter handles the integration layer. |
| **AI Pro (Managed)** | $59/month | 5 GB | 5 | Everything in Pro plus fully managed AI — hosting, storage, scaling, and AI processing all handled by Eddyter. Includes 1,000 AI credits per month. No AI provider setup required. |

**Enterprise:** Custom plans with enterprise-grade security, dedicated support, and higher limits are available. Contact sales for details.

**Free Trial:** New accounts get two weeks of free premium access with all AI features enabled.

**Starter vs Free:** Starter removes the monthly send/load constraints of the Free plan and gives you a real API key plus 1 GB secure storage — the minimum viable tier for a production side project or MVP.

**BYOK (Bring Your Own Key):** On the AI Pro plan, you supply your own LLM API key (OpenAI, Anthropic, etc.). Eddyter routes AI requests through your key, giving you full control over costs and model selection while Eddyter handles the editor-side integration.

**Add-ons available on paid plans:** Upgrade storage, upgrade AI credits, buy extra API keys.

**Compare plans in detail:** https://eddyter.com/pricing

---

## Getting Started

Integrate Eddyter into your React application in 10 minutes. Supports Next.js (App & Pages), Vite, and Webpack-based projects.

### 1. Installation

Install the core package via your preferred package manager:

```bash
npm install eddyter
```

Or with yarn / pnpm:

```bash
yarn add eddyter
# or
pnpm add eddyter
```

**npm:** https://www.npmjs.com/package/eddyter

### 2. Style Integration

Import the required CSS in your root file:

```tsx
import 'eddyter/style.css';
```

Place this import in `app/layout.tsx` (Next.js App Router), `pages/_app.tsx` (Pages Router), or your root `App.tsx`.

**Important:** Use `'eddyter/style.css'` — NOT `'eddyter/dist/style.css'`. The stylesheet is required for proper rendering of tables, toolbars, and all editor components. Missing styles will cause visual issues.

### 3. Get Your API Key

1. Create an account at [eddyter.com](https://www.eddyter.com/).
2. Subscribe to any plan on the [Pricing](https://eddyter.com/pricing) page.
3. Navigate to [License Keys](https://www.eddyter.com/user/license-key) in your dashboard.
4. Copy your API key.

Use `"YOUR_API_KEY"` as a placeholder in code examples. The key is retrieved from the Eddyter dashboard after subscribing.

### 4. Add the Editor to Your App

**Recommended approach for Next.js:** Use the `"use client"` directive at the top of your component file. Only fall back to `dynamic()` import with `ssr: false` if `"use client"` doesn't work.

```tsx
"use client";

import React from 'react';
import {
  ConfigurableEditorWithAuth,
  EditorProvider,
  defaultEditorConfig
} from 'eddyter';
import 'eddyter/style.css';

export default function Editor() {
  const apiKey = process.env.NEXT_PUBLIC_EDITOR_API_KEY!;

  // Current logged-in user for comments feature
  const currentUser = {
    id: 'user-123',
    name: 'John Doe',
    email: 'john@example.com',
    avatar: 'https://example.com/avatar.jpg' // optional
  };

  const handleContentChange = (html: string) => {
    console.log('Editor content:', html);
    // Save to state, database, etc.
  };

  return (
    <EditorProvider
      defaultFontFamilies={defaultEditorConfig.defaultFontFamilies}
      currentUser={currentUser}
    >
      <ConfigurableEditorWithAuth
        apiKey={apiKey}
        onChange={handleContentChange}
        initialContent="<p>Start writing...</p>"
        mentionUserList={['Alice', 'Bob', 'Charlie']}
        onAuthSuccess={() => console.log('Editor ready!')}
        onAuthError={(error) => console.error('Auth failed:', error)}
      />
    </EditorProvider>
  );
}
```

**Environment Variable:** Store your API key in environment variables (e.g. `NEXT_PUBLIC_EDITOR_API_KEY`). Never commit API keys to version control.

**Fallback (if `"use client"` doesn't work):**

```tsx
import dynamic from 'next/dynamic';

const Editor = dynamic(() => import('./Editor'), { ssr: false });
```

---

## Authentication

Standard API key verification enables premium features and AI capabilities.

### How It Works

1. Pass your API key to the `apiKey` prop.
2. The editor validates the key against Eddyter's server.
3. Features are enabled based on your subscription plan.
4. `onAuthSuccess` fires when validation succeeds.
5. `onAuthError` fires if validation fails.

### Custom Verification (Optional)

Provide your own verification function to validate keys through your backend:

```tsx
<ConfigurableEditorWithAuth
  apiKey={apiKey}
  customVerifyKey={async (key) => {
    const response = await fetch('/api/verify-editor-key', {
      method: 'POST',
      body: JSON.stringify({ key })
    });
    const data = await response.json();
    return {
      success: data.valid,
      message: data.message
    };
  }}
/>
```

---

## Features

A comprehensive toolset for modern content creation, from basic formatting to advanced AI generation.

### Classic Formatting

- **Basic Formatting** — Bold, italic, underline, strikethrough, subscript, superscript.
- **Text Colors** — Text color and background highlight with color picker.
- **Font Controls** — 20+ font families with adjustable font sizes and line height.
- **Text Alignment** — Left, center, right, and justify alignment.

### Lists and Structure

- **Bulleted Lists** — Custom bullet styles with proper nesting.
- **Numbered Lists** — Decimal, alpha, and roman numeral formats.
- **Checklists** — Interactive checkboxes with strikethrough.
- **Headings** — H1–H6 heading levels.
- **Note Panels** — Callout/note blocks for tips, warnings, and info.

### Tables

- **Table Operations** — Insert/delete rows and columns, merge cells.
- **Cell Resizing** — Drag to resize columns and rows.
- **Header Styling** — Distinct header row styling.
- **Context Menu** — Right-click menu for quick actions.

### Media Support

- **Images** — Drag-drop upload with 8-point resize handles.
- **Videos** — YouTube/Vimeo embed with responsive players.
- **File Attachments** — Upload and attach downloadable files.
- **Link Management** — Insert links with floating editor and preview.

### Collaboration

- **Comments** — Inline commenting powered by the `currentUser` prop.
- **@Mentions** — Tag users with the `mentionUserList` prop.

### AI Power (Premium)

Available on AI Pro (BYOK) and AI Managed plans.

- **Smart Chat** — In-editor AI assistant for research, drafting, and creative ideas.
- **Smart Autocomplete** — Predictive text suggestions as you type.
- **Refinement** — Instantly improve tone, fix grammar, or change content length.
- **Gen-AI Images** — Create custom visuals from text prompts inside your document.

### Slash Commands

Type `/` at the start of a line to open the quick formatting menu. Provides fast access to headings, lists, tables, images, embeds, and more without reaching for the toolbar.

---

## Configuration

Tailor every aspect of the editor to fit your application's specific needs.

### Toolbar Options

Control which toolbar buttons are visible. Pass as a prop to `ConfigurableEditorWithAuth`:

```tsx
<ConfigurableEditorWithAuth
  apiKey="YOUR_API_KEY"
  toolbarOptions={{
    enableUndoRedo: true,
    enableTextFormatting: true,
    enableAlignment: true,
    enableFontControls: true,
    enableTableOptions: true,
    enableInsertMenu: true,
    enableColors: true,
    enableClearOptions: true,
    enableEmojiPicker: true,
    enableLinks: true,
    enableFormatTextMenu: true,
    enableCodeFormat: true,
    enableAIChat: true,           // Premium — requires AI Pro or AI Managed plan
    enableTodoList: true,
    enableHtmlViewToggle: true,
    enableNotePanels: true,
    enableAutocompleteToggle: true
  }}
/>
```

All options default to `true`. Set any to `false` to hide that toolbar section.

### Floating Menu Options

Configure the selection-based floating toolbar that appears when text is highlighted:

```tsx
<ConfigurableEditorWithAuth
  apiKey="YOUR_API_KEY"
  floatingMenuOptions={{
    bold: true,
    italic: true,
    underline: true,
    uppercase: true,
    lowercase: true,
    capitalize: true,
    strikethrough: true,
    subscript: true,
    superscript: true,
    code: true,
    link: true,
    aiChat: true,      // Premium
    comment: true,
    improve: true       // AI improve text — Premium
  }}
/>
```

### Toolbar Behavior

Configure toolbar positioning with the `toolbar` prop. In sticky mode you can set `offset` and `zIndex`. In static mode those values are ignored.

```tsx
// Sticky toolbar below a 64px fixed header
<ConfigurableEditorWithAuth
  apiKey="YOUR_API_KEY"
  toolbar={{ mode: "sticky", offset: 64, zIndex: 1200 }}
/>
```

**Defaults:** `{ mode: "sticky", offset: 20, zIndex: 1000 }`

**Note:** The `toolbar` prop is an OBJECT, not an array.

### Editor Scroll Area

In static toolbar mode, use `editor.maxHeight` to make only the editor text area scrollable:

```tsx
// Static toolbar with scrollable content area
<ConfigurableEditorWithAuth
  apiKey="YOUR_API_KEY"
  toolbar={{ mode: "static" }}
  editor={{ maxHeight: 600 }}
/>
```

---

## Keyboard Shortcuts

Speed up your workflow with standard keyboard shortcuts.

### Text Formatting

| Action | Shortcut |
|---|---|
| Bold | Ctrl/Cmd + B |
| Italic | Ctrl/Cmd + I |
| Underline | Ctrl/Cmd + U |
| Insert Link | Ctrl/Cmd + K |

### General

| Action | Shortcut |
|---|---|
| Undo | Ctrl/Cmd + Z |
| Redo | Ctrl/Cmd + Y |
| Select All | Ctrl/Cmd + A |
| Paste | Ctrl/Cmd + V |

### Quick Access

| Action | Shortcut |
|---|---|
| Slash Commands | Type `/` at line start |

---

## API Reference

### `<EditorProvider>`

Provides context and configuration for the editor. Must wrap the editor component to enable all features.

| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
| `children` | `ReactNode` | Yes | — | The wrapped content (your editor component). |
| `defaultFontFamilies` | `string[]` | No | Built-in list | Override the list of available font families. Use `defaultEditorConfig.defaultFontFamilies` for the standard set. |
| `currentUser` | `CurrentUser` | No | — | User info for the comments feature. Object with `id`, `name`, `email`, and optional `avatar` fields. |
| `apiKey` | `string` | No | — | API key for read-only/preview mode contexts. |

### `<ConfigurableEditorWithAuth>`

The core editor component with built-in subscription verification and AI service integration.

| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
| `apiKey` | `string` | **Yes** | — | Your Eddyter subscription key. |
| `initialContent` | `string` | No | `""` | Default HTML content to populate the editor. Use `initialContent`, NOT `value`. |
| `onChange` | `(html: string) => void` | No | — | Callback that fires on every content change, returning the current HTML string. |
| `mode` | `"edit" \| "preview"` | No | `"edit"` | `"edit"` enables full editing; `"preview"` renders content read-only. |
| `toolbar` | `{ mode?: "sticky" \| "static"; offset?: number; zIndex?: number }` | No | `{ mode: "sticky", offset: 20, zIndex: 1000 }` | Toolbar positioning config. This is an OBJECT, not an array. |
| `editor` | `{ maxHeight?: number }` | No | — | Editor area config. Use `maxHeight` in static toolbar mode to constrain the scrollable content area. |
| `toolbarOptions` | `ToolbarOptions` | No | All `true` | Object of boolean flags to show/hide individual toolbar sections. See Configuration section. |
| `floatingMenuOptions` | `FloatingMenuOptions` | No | All `true` | Object of boolean flags to configure the text-selection floating menu. See Configuration section. |
| `mentionUserList` | `string[]` | No | `[]` | List of user names available for @mention autocomplete. |
| `onAuthSuccess` | `() => void` | No | — | Fires when API key validation succeeds. |
| `onAuthError` | `(error: Error) => void` | No | — | Fires when API key validation fails. |
| `customVerifyKey` | `(key: string) => Promise<{ success: boolean; message?: string }>` | No | — | Custom async function to verify the API key through your own backend. |

### `CurrentUser` Type

```tsx
interface CurrentUser {
  id: string;       // Unique user identifier
  name: string;     // Display name
  email: string;    // User email
  avatar?: string;  // Optional avatar URL
}
```

### Helper Exports

| Export | Type | Description |
|---|---|---|
| `defaultEditorConfig` | `object` | Contains `defaultFontFamilies` and other default configuration values. |

---

## Code Examples

### Basic Editor

```tsx
"use client";

import { ConfigurableEditorWithAuth, EditorProvider } from 'eddyter';
import 'eddyter/style.css';

export default function BasicEditor() {
  return (
    <EditorProvider>
      <ConfigurableEditorWithAuth
        apiKey="YOUR_API_KEY"
        onAuthSuccess={() => console.log('Ready!')}
      />
    </EditorProvider>
  );
}
```

### Editor with State Management

```tsx
"use client";

import { useState } from 'react';
import { ConfigurableEditorWithAuth, EditorProvider } from 'eddyter';
import 'eddyter/style.css';

export default function EditorWithState() {
  const [content, setContent] = useState('<p>Start writing...</p>');

  return (
    <EditorProvider>
      <ConfigurableEditorWithAuth
        apiKey="YOUR_API_KEY"
        initialContent={content}
        onChange={setContent}
      />
    </EditorProvider>
  );
}
```

### Customized Toolbar (Minimal Setup)

```tsx
"use client";

import { ConfigurableEditorWithAuth, EditorProvider } from 'eddyter';
import 'eddyter/style.css';

export default function MinimalEditor() {
  return (
    <EditorProvider>
      <ConfigurableEditorWithAuth
        apiKey="YOUR_API_KEY"
        toolbarOptions={{
          enableUndoRedo: true,
          enableTextFormatting: true,
          enableAlignment: true,
          enableFontControls: false,
          enableTableOptions: false,
          enableInsertMenu: true,
          enableColors: false,
          enableClearOptions: true,
          enableEmojiPicker: false,
          enableLinks: true,
          enableFormatTextMenu: true,
          enableCodeFormat: false,
          enableAIChat: true,
          enableTodoList: true,
          enableHtmlViewToggle: false,
          enableNotePanels: false,
          enableAutocompleteToggle: false
        }}
        toolbar={{ mode: "sticky", offset: 0 }}
      />
    </EditorProvider>
  );
}
```

### Full-Featured Editor with Comments and Mentions

```tsx
"use client";

import { useState } from 'react';
import {
  ConfigurableEditorWithAuth,
  EditorProvider,
  defaultEditorConfig
} from 'eddyter';
import 'eddyter/style.css';

export default function FullEditor() {
  const [content, setContent] = useState('');

  const currentUser = {
    id: 'user-001',
    name: 'Jane Smith',
    email: 'jane@example.com',
    avatar: 'https://example.com/jane.jpg'
  };

  return (
    <EditorProvider
      defaultFontFamilies={defaultEditorConfig.defaultFontFamilies}
      currentUser={currentUser}
    >
      <ConfigurableEditorWithAuth
        apiKey={process.env.NEXT_PUBLIC_EDITOR_API_KEY!}
        initialContent={content}
        onChange={setContent}
        mentionUserList={['Alice', 'Bob', 'Charlie', 'David']}
        toolbar={{ mode: "sticky", offset: 64, zIndex: 1200 }}
        onAuthSuccess={() => console.log('Editor authenticated!')}
        onAuthError={(err) => console.error('Auth failed:', err)}
      />
    </EditorProvider>
  );
}
```

### Preview / Read-Only Mode

```tsx
"use client";

import { ConfigurableEditorWithAuth, EditorProvider } from 'eddyter';
import 'eddyter/style.css';

export default function PreviewMode({ content }: { content: string }) {
  return (
    <EditorProvider>
      <ConfigurableEditorWithAuth
        apiKey="YOUR_API_KEY"
        initialContent={content}
        mode="preview"
      />
    </EditorProvider>
  );
}
```

---

## Theming

### CSS Variable Customization

The editor exposes CSS variables under the `--cteditorf47ac10b-*` namespace. Apply overrides inside a `.eddyter-scope` selector to customize colors, backgrounds, borders, and more.

```css
.eddyter-scope {
  --cteditorf47ac10b-background: #ffffff;
  --cteditorf47ac10b-foreground: #1a1a1a;
  --cteditorf47ac10b-primary: #2563eb;
  --cteditorf47ac10b-border: #e5e7eb;
  /* ... additional variables */
}
```

### Force Theme

If your application supports only one theme:

- **Dark-only:** Target `.eddyter-scope` with dark-mode variables.
- **Light-only:** Target `.dark .eddyter-scope.dark` with light-mode variables.

See the full CSS variable list with default values at https://eddyter.com/docs#theming.

---

## Common Pitfalls

| Mistake | Fix |
|---|---|
| Importing `'eddyter/dist/style.css'` | Use `'eddyter/style.css'` — no `dist/` prefix. |
| Using `value` prop for content | Use `initialContent` — there is no `value` prop. |
| Passing `toolbar` as an array | `toolbar` is an OBJECT: `{ mode, offset, zIndex }`. |
| Missing `"use client"` in Next.js | Add `"use client"` at the top of your editor component file. |
| Committing API key to source code | Store in environment variables (e.g. `NEXT_PUBLIC_EDITOR_API_KEY`). |
| Wrapping editor without `EditorProvider` | `ConfigurableEditorWithAuth` must be inside `<EditorProvider>`. |

---

## Migrating from Legacy Editors

Eddyter is designed as a drop-in replacement for legacy WYSIWYG editors. If you're migrating from TinyMCE, CKEditor, Quill, or similar:

1. **Content compatibility:** Eddyter accepts standard HTML via `initialContent`, so existing stored content works out of the box.
2. **Event model:** Replace `onChange` / `onEditorChange` callbacks with Eddyter's `onChange` prop, which returns an HTML string.
3. **Toolbar mapping:** Most toolbar features (bold, italic, tables, lists, links, images) have direct equivalents. Use `toolbarOptions` to match your current feature set.
4. **AI upgrade:** Unlike legacy editors, AI features (chat, autocomplete, refinement, image generation) are built in — no plugins or third-party integrations required.

---

## Support & Resources

- **Documentation** — Full docs: https://eddyter.com/docs
- **Live Demo** — Try the editor: https://eddyter.com
- **Get API Key** — Manage license: https://www.eddyter.com/user/license-key
- **Pricing** — Compare plans: https://eddyter.com/pricing
- **Support** — Team assistance: https://www.eddyter.com/support
- **Tutorials** — Video walkthroughs: https://eddyter.com/tutorials
- **Release Notes** — Shipped updates: https://eddyter.com/release-notes
- **npm Package** — https://www.npmjs.com/package/eddyter

### Video Tutorials

- **What is Eddyter? Why Developers Are Switching to This AI Editor (2026):** https://youtu.be/oNHBa-DImZc
- **Integrate Eddyter in 30 Minutes Using AI Tools (Cursor, Claude, Lovable):** https://youtu.be/5lTjRFjUWgs

### Bug Reports & Support

Eddyter's repository is private. Report bugs through the in-product bug reporter or via https://www.eddyter.com/support — not through GitHub.

### License

Eddyter is licensed under the MIT License. Security, privacy, and compliance are our core technical principles.