UI Components Overview - Yoopta Editor

Introduction

The @yoopta/ui package provides a collection of headless UI components that give you complete control over your editor’s interface. These components follow modern design patterns and best practices, offering flexibility and customization while maintaining excellent developer experience.

Starting with Yoopta Editor v4.10+, the core @yoopta/editor is completely headless. All UI components have been moved to the separate @yoopta/ui package, giving you full control over appearance and behavior.

Key Features

Fully Customizable

Every component supports custom styling through CSS variables, Tailwind classes, or inline styles

Compound Components

Built with the compound component pattern for maximum flexibility and composition

TypeScript Support

Full TypeScript support with exported types for every component and hook

Accessibility

Built with accessibility in mind, following ARIA best practices

Installation

npm install @yoopta/ui
# or
yarn add @yoopta/ui

Import Styles

Two ways to import the @yoopta/ui package:

1. Full Package Import

Import everything from the main entry point:

import {
  Toolbar,
  ActionMenuList,
  SlashCommandMenu,
  FloatingBlockActions,
  BlockOptions,
  useToolbar,
  useActionMenuList,
} from '@yoopta/ui';

2. Subpath Imports (Recommended for Bundle Size)

Import only what you need using subpath exports for better tree-shaking and smaller bundles:

// Only import the toolbar (smaller bundle)
import { Toolbar, useToolbar } from '@yoopta/ui/toolbar';

// Only import action menu list
import { ActionMenuList, useActionMenuList } from '@yoopta/ui/action-menu-list';

// Only import slash command menu
import { SlashCommandMenu, useSlashCommand } from '@yoopta/ui/slash-command-menu';

// Other available subpaths
import { FloatingBlockActions } from '@yoopta/ui/floating-block-actions';
import { BlockOptions } from '@yoopta/ui/block-options';
import { SelectionBox } from '@yoopta/ui/selection-box';
import { HighlightColorPicker } from '@yoopta/ui/highlight-color-picker';
import { Portal } from '@yoopta/ui/portal';
import { Overlay } from '@yoopta/ui/overlay';
import { ThemeProvider, useTheme } from '@yoopta/ui/theme';

When to use subpath imports:

You only need 1-2 components
Bundle size is critical (e.g., landing pages)
You want explicit control over what’s included

When to use full import:

You use most components
Convenience over optimization
Your bundler has good tree-shaking

Available Subpaths

Subpath	Exports
`@yoopta/ui`	Everything (convenience)
`@yoopta/ui/toolbar`	`Toolbar`, `useToolbar`, `useToolbarStore`
`@yoopta/ui/action-menu-list`	`ActionMenuList`, `useActionMenuList`, `useActionMenuListActions`
`@yoopta/ui/slash-command-menu`	`SlashCommandMenu`, `useSlashCommand`, context hooks
`@yoopta/ui/floating-block-actions`	`FloatingBlockActions`, `useFloatingBlockActions`
`@yoopta/ui/block-options`	`BlockOptions`, `useBlockOptions`, `useBlockOptionsActions`
`@yoopta/ui/selection-box`	`SelectionBox`, `useRectangeSelectionBox`
`@yoopta/ui/highlight-color-picker`	`HighlightColorPicker`
`@yoopta/ui/portal`	`Portal`
`@yoopta/ui/overlay`	`Overlay`
`@yoopta/ui/theme`	`ThemeProvider`, `useTheme`, `ThemeToggle`

Available Components

Core UI Components

FloatingBlockActions

Floating buttons that appear when hovering over blocks

BlockOptions

Context menu for block actions (duplicate, delete, etc.)

Toolbar

Floating toolbar for text formatting on selection

ActionMenuList

Dropdown menu for block type selection

SlashActionMenuList

Slash command menu for quick block insertion

SelectionBox

Rectangle selection for selecting multiple blocks

Theme System

Built-in theme system with light/dark mode support

Architecture

Component Types

Yoopta UI components fall into two categories:

1. Self-Managed Components

These components automatically manage their own state and behavior:

FloatingBlockActions - Appears on block hover
Toolbar - Appears on text selection
SlashActionMenuList - Appears on / command

// Just render them - they handle everything automatically
<YooptaEditor>
  <FloatingBlockActions>
    <FloatingBlockActions.Button onClick={...}>
      <PlusIcon />
    </FloatingBlockActions.Button>
  </FloatingBlockActions>
</YooptaEditor>

2. Controlled Components

These components are controlled programmatically:

BlockOptions - Opened via useBlockOptionsActions()
ActionMenuList - Opened via useActionMenuListActions()

// Control them via hooks
const { open } = useBlockOptionsActions();

const handleClick = () => {
  open({ reference: element, blockId: 'block-id' });
};

Two-Hook Pattern

Many components follow the two-hook pattern:

Full Hook - For the component that renders the UI (includes Floating UI, event listeners, etc.)
Lightweight Hook - For other components that just need to interact with the UI

// In component that renders UI
const { isOpen, getRootProps, getItemProps } = useToolbar();

// In other components that need to control it
const { open, close } = useToolbarActions();

Quick Start

Here’s a complete example using the new UI components:

import { createYooptaEditor, YooptaEditor } from '@yoopta/editor';

// Option 1: Full import
import {
  FloatingBlockActions,
  BlockOptions,
  Toolbar,
  SlashCommandMenu,
  useFloatingBlockActions,
  useBlockOptions,
  useToolbar,
} from '@yoopta/ui';

// Option 2: Subpath imports (better for bundle size)
// import { FloatingBlockActions, useFloatingBlockActions } from '@yoopta/ui/floating-block-actions';
// import { Toolbar, useToolbar } from '@yoopta/ui/toolbar';
// import { SlashCommandMenu } from '@yoopta/ui/slash-command-menu';

// FloatingBlockActions Component
const MyFloatingBlockActions = () => {
  const { floatingBlockId } = useFloatingBlockActions();
  const editor = useYooptaEditor();

  const onPlusClick = () => {
    editor.insertBlock('Paragraph', { at: editor.path.current, focus: true });
  };

  return (
    <FloatingBlockActions.Root>
      <FloatingBlockActions.Button onClick={onPlusClick}>
        <PlusIcon />
      </FloatingBlockActions.Button>
    </FloatingBlockActions.Root>
  );
};

// Toolbar Component
const MyToolbar = () => {
  const { isOpen, getRootProps } = useToolbar();
  const editor = useYooptaEditor();

  if (!isOpen) return null;

  return (
    <Toolbar.Root {...getRootProps()}>
      <Toolbar.Group>
        <Toolbar.Button onClick={editor.formats.bold?.toggle}>
          <BoldIcon />
        </Toolbar.Button>
      </Toolbar.Group>
    </Toolbar.Root>
  );
};

// Main Editor
function App() {
  const editor = useMemo(() => createYooptaEditor(), []);

  return (
    <YooptaEditor editor={editor} plugins={plugins} marks={marks}>
      <MyFloatingBlockActions />
      <MyToolbar />
    </YooptaEditor>
  );
}

Styling

CSS Variables

All components use CSS variables (shadcn/ui style) for theming:

:root {
  --yoopta-ui-background: 0 0% 100%;
  --yoopta-ui-foreground: 222.2 84% 4.9%;
  --yoopta-ui-border: 214.3 31.8% 91.4%;
  --yoopta-ui-accent: 210 40% 96.1%;
  /* ...more variables */
}

.dark {
  --yoopta-ui-background: 222.2 84% 4.9%;
  --yoopta-ui-foreground: 210 40% 98%;
  /* ...dark theme variables */
}

Custom Styles

Override styles using:

CSS Variables - Change theme globally
CSS Classes - Target specific elements
Inline Styles - Component-level customization
Tailwind - Use utility classes directly

<Toolbar.Root className="bg-slate-800 shadow-xl" style={{ borderRadius: '12px' }}>
  {/* ... */}
</Toolbar.Root>

State Management

UI components use Zustand for state management, allowing:

✅ Shared state across components
✅ Singleton stores (one instance per component type)
✅ Programmatic control from anywhere
✅ Lightweight and performant

// Open BlockOptions from any component
const { open } = useBlockOptionsActions();
open({ reference: element, blockId: 'block-123' });

// The BlockOptions component will automatically show

TypeScript Support

Full TypeScript support with exported types:

import type {
  FloatingBlockActionsProps,
  BlockOptionsProps,
  ToolbarProps,
  ActionMenuItem,
} from '@yoopta/ui';

Migration from v4.9

If you’re migrating from the old built-in UI:

The old ActionMenuTool, Toolbar, and LinkTool from @yoopta/tools are deprecated. Use the new components from @yoopta/ui instead.

Before (v4.9):

import ActionMenuList from '@yoopta/action-menu';
import Toolbar from '@yoopta/toolbar';

<YooptaEditor tools={[ActionMenuList, Toolbar]} />;

After (v6):

import { SlashActionMenuList, Toolbar } from '@yoopta/ui';

<YooptaEditor>
  <MySlashActionMenuList />
  <MyToolbar />
</YooptaEditor>;

Next Steps

FloatingBlockActions

Learn about the floating block actions component

Toolbar

Build a custom formatting toolbar

Theme System

Implement light/dark mode switching

Examples

See complete examples

Getting Started

Core Concepts

Plugins

Marks

UI Components

Advanced

API Reference

Examples

​Introduction

​Key Features

Fully Customizable

Compound Components

TypeScript Support

Accessibility

​Installation

​Import Styles

​1. Full Package Import

​2. Subpath Imports (Recommended for Bundle Size)

​Available Subpaths

​Available Components

​Core UI Components

FloatingBlockActions

BlockOptions

Toolbar

ActionMenuList

SlashActionMenuList

SelectionBox

Theme System

​Architecture

​Component Types

​1. Self-Managed Components

​2. Controlled Components

​Two-Hook Pattern

​Quick Start

​Styling

​CSS Variables

​Custom Styles

​State Management

​TypeScript Support

​Migration from v4.9

​Next Steps

FloatingBlockActions

Toolbar

Theme System

Examples

Introduction

Key Features

Installation

Import Styles

1. Full Package Import

2. Subpath Imports (Recommended for Bundle Size)

Available Subpaths

Available Components

Core UI Components

Architecture

Component Types

1. Self-Managed Components

2. Controlled Components

Two-Hook Pattern

Quick Start

Styling

CSS Variables

Custom Styles

State Management

TypeScript Support

Migration from v4.9

Next Steps