Svelty Editor

Welcome to Svelty Editor documentation! This guide will help you understand what Svelty Editor is, how it works, and how to use it effectively in your Svelte applications.

What is Svelty Editor?

Svelty Editor is a powerful block-styled editor wrapper for Editor.js, specifically designed for Svelte applications. It provides a modern, extensible editing experience with full TypeScript support and enhanced configuration options.

Key Benefits

• Svelte Integration — Seamlessly integrates with your Svelte applications with proper lifecycle management and reactive updates.
• Type Safety — Built with TypeScript from the ground up, providing excellent type inference and development experience.
• Extensible — Easy to extend with custom blocks, tools, and configurations.
• Performance — Optimized for performance with dynamic tool loading and efficient updates.

Core Concepts

Block Editor

Svelty Editor is based on the block editor concept. Instead of a single contenteditable field, content is divided into blocks, each serving a specific purpose (paragraphs, headers, lists, etc.).

<SveltyEditor
  data={{
    blocks: [
      {
        type: "header",
        data: {
          text: "Welcome to Svelty Editor",
          level: 1
        }
      },
      {
        type: "paragraph",
        data: {
          text: "Start writing amazing content..."
        }
      }
    ]
  }}
/>

Tools

Tools are the building blocks of the editor. Each tool represents a type of content (like paragraphs, headers, lists) and defines how that content is created, edited, and rendered.

const config = {
  tools: {
    header: Header,
    list: List,
    paragraph: {
      class: Paragraph,
      inlineToolbar: true,
      config: {
        placeholder: 'Write something...'
      }
    }
  }
};

Block Tunes

Block Tunes are special tools that modify blocks. They appear in the block’s settings menu and can affect how the block behaves or is displayed.

const config = {
  tunes: ['alignment', 'delete'],
  tools: {
    paragraph: {
      tunes: ['alignment']
    }
  }
};

Getting Started

Installation

npm install svelty-editor @editorjs/editorjs

Basic Setup

Create your first editor instance:

<script lang="ts">
  import { SveltyEditor } from 'svelty-editor';
  import type { OutputData } from '@editorjs/editorjs';

  const handleChange = (data: OutputData) => {
    console.log('Content updated:', data);
  };
</script>

<SveltyEditor
  onChange={handleChange}
  placeholder="Start writing..."
/>

Architecture

Svelty Editor follows a modular architecture:

• Core Editor — Manages the main editing functionality
• Tool System — Handles block tools and their interactions
• Event System — Manages editor events and updates
• Rendering Layer — Handles the UI representation
• Data Layer — Manages content state and persistence

Common Use Cases

Rich Text Editing

Perfect for content management systems, blog editors, or any application requiring rich text editing capabilities.

Document Creation

Create structured documents with various content types, perfect for documentation systems or knowledge bases.

Interactive Content

Build interactive content with custom blocks for embedded content, interactive elements, or specialized formatting.

Best Practices

Performance

Dynamic Imports — Load tools dynamically to reduce initial bundle size:

tools: {
  header: () => import('@editorjs/header')
}

Efficient Updates — Use the onChange callback judiciously:

<SveltyEditor
  onChange={(data) => {
    // Debounce or throttle heavy operations
    debouncedUpdate(data);
  }}
/>

Type Safety

Use TypeScript — Take advantage of built-in type definitions:

import type { EditorConfig, OutputData } from 'svelty-editor';

Custom Tool Types — Define proper types for custom tools:

interface CustomToolConfig {
  placeholder: string;
  maxLength?: number;
}

State Management

Content Persistence — Implement proper save strategies:

const handleSave = async () => {
  const data = await editor.save();
  await saveToDatabase(data);
};

Error Handling — Implement proper error boundaries:

<div class="editor-wrapper">
  {#try}
    <SveltyEditor {...config} />
  {:catch error}
    <div class="error-boundary">
      Error loading editor: {error.message}
    </div>
  {/try}
</div>