ElementOptions

Overview

ElementOptions is a compound component for building inline configuration popovers attached to elements. It provides form controls (Select, Toggle, Slider, ColorPicker, Input) and helper hooks for updating element properties.

Features

Compound components — Root, Trigger, Content, Group, Label, Separator
Form controls — Select, Toggle, Slider, ColorPicker, Input
Helper hooks — useElementOptions, useUpdateElementProps
Radix UI — Built on Radix Popover for accessibility and positioning

Installation

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

Basic Usage

import { ElementOptions, useElementOptions, useUpdateElementProps } from '@yoopta/ui/element-options';

// In your element render component
function MyElement({ attributes, children, element, blockId }) {
  return (
    <div {...attributes} className="group relative">
      <ElementOptions.Root blockId={blockId} element={element}>
        <ElementOptions.Trigger className="absolute right-0 top-0 opacity-0 group-hover:opacity-100" />
        <MyElementOptions />
      </ElementOptions.Root>
      {children}
    </div>
  );
}

// Options content component
function MyElementOptions() {
  const { element } = useElementOptions();
  const updateProps = useUpdateElementProps<{ theme: string }>();

  return (
    <ElementOptions.Content side="bottom" align="end">
      <ElementOptions.Group>
        <ElementOptions.Label>Theme</ElementOptions.Label>
        <ElementOptions.Select
          value={element.props?.theme ?? 'default'}
          options={[
            { value: 'default', label: 'Default' },
            { value: 'info', label: 'Info' },
          ]}
          onValueChange={(value) => updateProps({ theme: value })}
        />
      </ElementOptions.Group>
    </ElementOptions.Content>
  );
}

API Reference

`ElementOptions.Root`

Root component that provides context and manages popover state.

<ElementOptions.Root blockId={blockId} element={element}>
  {children}
</ElementOptions.Root>

Props:

Prop	Type	Description
`blockId`	`string`	Block ID containing element
`element`	`SlateElement`	The element being configured
`children`	`ReactNode`	Trigger and Content
`className`	`string`	Custom CSS classes
`style`	`CSSProperties`	Custom inline styles

`ElementOptions.Trigger`

Button that opens the options popover.

<ElementOptions.Trigger className="opacity-0 group-hover:opacity-100">
  <SettingsIcon />
</ElementOptions.Trigger>

Props:

Prop	Type	Description
`children`	`ReactNode`	Custom icon (defaults to MoreHorizontal)
`className`	`string`	Custom CSS classes
`style`	`CSSProperties`	Custom inline styles

`ElementOptions.Content`

Floating content panel containing form controls.

<ElementOptions.Content side="bottom" align="end" sideOffset={8}>
  {/* Groups and controls here */}
</ElementOptions.Content>

Props:

Prop	Type	Default	Description
`side`	`'top' \| 'right' \| 'bottom' \| 'left'`	`'bottom'`	Placement side
`align`	`'start' \| 'center' \| 'end'`	`'end'`	Alignment
`sideOffset`	`number`	`4`	Offset from trigger
`alignOffset`	`number`	`0`	Alignment offset
`className`	`string`		Custom CSS classes

`ElementOptions.Group`

Groups related controls together.

<ElementOptions.Group>
  <ElementOptions.Label>Settings</ElementOptions.Label>
  {/* Controls here */}
</ElementOptions.Group>

`ElementOptions.Label`

Label for a group of controls.

<ElementOptions.Label>Theme</ElementOptions.Label>

`ElementOptions.Separator`

Visual separator between groups.

<ElementOptions.Separator />

`ElementOptions.Select`

Dropdown select for choosing from predefined options.

<ElementOptions.Select
  value={currentValue}
  options={[
    { value: 'solid', label: 'Solid' },
    { value: 'dashed', label: 'Dashed', icon: <DashedIcon /> },
  ]}
  onValueChange={(value) => updateProps({ style: value })}
  renderOption={(option) => <span>{option.icon} {option.label}</span>}
  renderValue={(option) => <span>{option?.label}</span>}
/>

Props:

Prop	Type	Description
`value`	`T`	Current selected value
`options`	`SelectOption<T>[]`	Available options
`onValueChange`	`(value: T) => void`	Called when selection changes
`placeholder`	`string`	Placeholder text
`renderOption`	`(option: SelectOption<T>) => ReactNode`	Custom option renderer
`renderValue`	`(option?: SelectOption<T>) => ReactNode`	Custom value renderer

SelectOption type:

type SelectOption<T> = {
  value: T;
  label: string;
  icon?: ReactNode;
  color?: string;
};

`ElementOptions.Toggle`

Boolean toggle switch.

<ElementOptions.Toggle
  checked={isEnabled}
  onCheckedChange={(checked) => updateProps({ enabled: checked })}
  label="Enable feature"
/>

Props:

Prop	Type	Description
`checked`	`boolean`	Current state
`onCheckedChange`	`(checked: boolean) => void`	Called when toggled
`label`	`string`	Optional label text

`ElementOptions.Slider`

Numeric slider for range values.

<ElementOptions.Slider
  value={50}
  onValueChange={(value) => updateProps({ opacity: value })}
  min={0}
  max={100}
  step={1}
/>

Props:

Prop	Type	Default	Description
`value`	`number`		Current value
`onValueChange`	`(value: number) => void`		Called on change
`min`	`number`	`0`	Minimum value
`max`	`number`	`100`	Maximum value
`step`	`number`	`1`	Step increment

`ElementOptions.ColorPicker`

Color picker with presets and hex input.

<ElementOptions.ColorPicker
  value="#3B82F6"
  onChange={(color) => updateProps({ color })}
  presetColors={['#EF4444', '#22C55E', '#3B82F6', '#8B5CF6']}
/>

Props:

Prop	Type	Description
`value`	`string`	Current color (hex)
`onChange`	`(color: string) => void`	Called on change
`presetColors`	`string[]`	Preset color swatches

`ElementOptions.Input`

Text input for string values.

<ElementOptions.Input
  value={title}
  onChange={(value) => updateProps({ title: value })}
  placeholder="Enter title..."
  type="text"
/>

Props:

Prop	Type	Default	Description
`value`	`string`		Current value
`onChange`	`(value: string) => void`		Called on change
`placeholder`	`string`		Placeholder text
`type`	`'text' \| 'number' \| 'url'`	`'text'`	Input type

Hooks

`useElementOptions()`

Access element context within Content.

const { blockId, element, editor, isOpen, setIsOpen } = useElementOptions();

Returns:

Property	Type	Description
`blockId`	`string`	Block ID
`element`	`SlateElement`	Current element
`editor`	`YooEditor`	Editor instance
`isOpen`	`boolean`	Popover open state
`setIsOpen`	`(open: boolean) => void`	Toggle popover

`useUpdateElementProps<T>()`

Helper hook for updating element properties.

const updateProps = useUpdateElementProps<{ theme: string; color: string }>();

// Usage
updateProps({ theme: 'info' });
updateProps({ color: '#3B82F6' });

Examples

Callout Theme Selector

const CALLOUT_THEMES = [
  { value: 'default', label: 'Default', icon: <MessageSquare className="h-4 w-4" /> },
  { value: 'info', label: 'Info', icon: <Info className="h-4 w-4 text-blue-500" /> },
  { value: 'success', label: 'Success', icon: <CheckCircle className="h-4 w-4 text-green-500" /> },
  { value: 'warning', label: 'Warning', icon: <AlertCircle className="h-4 w-4 text-yellow-500" /> },
  { value: 'error', label: 'Error', icon: <XCircle className="h-4 w-4 text-red-500" /> },
];

function CalloutElementOptions() {
  const { element } = useElementOptions();
  const updateProps = useUpdateElementProps<{ theme: string }>();

  return (
    <ElementOptions.Content side="bottom" align="end" sideOffset={8}>
      <ElementOptions.Group>
        <ElementOptions.Label>Theme</ElementOptions.Label>
        <ElementOptions.Select
          value={element.props?.theme ?? 'default'}
          options={CALLOUT_THEMES}
          onValueChange={(value) => updateProps({ theme: value })}
          renderOption={(option) => (
            <span className="flex items-center gap-2">
              {option.icon}
              {option.label}
            </span>
          )}
        />
      </ElementOptions.Group>
    </ElementOptions.Content>
  );
}

Divider with Style and Color

const DIVIDER_THEMES = [
  { value: 'solid', label: 'Solid' },
  { value: 'dashed', label: 'Dashed' },
  { value: 'dotted', label: 'Dotted' },
  { value: 'gradient', label: 'Gradient' },
];

const DIVIDER_COLORS = ['#E5E7EB', '#6B7280', '#EF4444', '#22C55E', '#3B82F6'];

function DividerElementOptions() {
  const { element } = useElementOptions();
  const updateProps = useUpdateElementProps<{ theme: string; color: string }>();

  return (
    <ElementOptions.Content side="bottom" align="end" sideOffset={8}>
      <ElementOptions.Group>
        <ElementOptions.Label>Style</ElementOptions.Label>
        <ElementOptions.Select
          value={element.props?.theme ?? 'solid'}
          options={DIVIDER_THEMES}
          onValueChange={(value) => updateProps({ theme: value })}
        />
      </ElementOptions.Group>

      <ElementOptions.Separator />

      <ElementOptions.Group>
        <ElementOptions.Label>Color</ElementOptions.Label>
        <ElementOptions.ColorPicker
          value={element.props?.color ?? '#E5E7EB'}
          onChange={(color) => updateProps({ color })}
          presetColors={DIVIDER_COLORS}
        />
      </ElementOptions.Group>
    </ElementOptions.Content>
  );
}

Table Appearance Toggles

function TableElementOptions() {
  const { element } = useElementOptions();
  const updateProps = useUpdateElementProps<{
    bordered: boolean;
    compact: boolean;
    scrollable: boolean;
  }>();
  const props = element.props ?? {};

  return (
    <ElementOptions.Content side="bottom" align="end" sideOffset={8}>
      <ElementOptions.Group>
        <ElementOptions.Label>Appearance</ElementOptions.Label>

        <div className="flex items-center justify-between px-2">
          <span>Bordered</span>
          <ElementOptions.Toggle
            checked={props.bordered ?? true}
            onCheckedChange={(checked) => updateProps({ bordered: checked })}
          />
        </div>

        <div className="flex items-center justify-between px-2">
          <span>Compact</span>
          <ElementOptions.Toggle
            checked={props.compact ?? false}
            onCheckedChange={(checked) => updateProps({ compact: checked })}
          />
        </div>

        <div className="flex items-center justify-between px-2">
          <span>Scrollable</span>
          <ElementOptions.Toggle
            checked={props.scrollable ?? true}
            onCheckedChange={(checked) => updateProps({ scrollable: checked })}
          />
        </div>
      </ElementOptions.Group>
    </ElementOptions.Content>
  );
}

Table of Contents with Input and Toggles

const DEPTH_OPTIONS = [
  { value: '1', label: 'H1 only' },
  { value: '2', label: 'H1 – H2' },
  { value: '3', label: 'H1 – H3' },
];

function TocElementOptions() {
  const { element } = useElementOptions();
  const updateProps = useUpdateElementProps<{
    title: string;
    depth: number;
    showNumbers: boolean;
    collapsible: boolean;
  }>();
  const props = element.props ?? {};

  return (
    <ElementOptions.Content side="bottom" align="end" sideOffset={8}>
      <ElementOptions.Group>
        <ElementOptions.Label>Title</ElementOptions.Label>
        <ElementOptions.Input
          value={props.title ?? 'Table of Contents'}
          onChange={(value) => updateProps({ title: value })}
          placeholder="Title..."
        />
      </ElementOptions.Group>

      <ElementOptions.Separator />

      <ElementOptions.Group>
        <ElementOptions.Label>Depth</ElementOptions.Label>
        <ElementOptions.Select
          value={String(props.depth ?? 3)}
          options={DEPTH_OPTIONS}
          onValueChange={(value) => updateProps({ depth: Number(value) })}
        />
      </ElementOptions.Group>

      <ElementOptions.Separator />

      <ElementOptions.Group>
        <div className="flex items-center justify-between px-2">
          <span>Numbered</span>
          <ElementOptions.Toggle
            checked={props.showNumbers ?? false}
            onCheckedChange={(checked) => updateProps({ showNumbers: checked })}
          />
        </div>
        <div className="flex items-center justify-between px-2">
          <span>Collapsible</span>
          <ElementOptions.Toggle
            checked={props.collapsible ?? false}
            onCheckedChange={(checked) => updateProps({ collapsible: checked })}
          />
        </div>
      </ElementOptions.Group>
    </ElementOptions.Content>
  );
}

Styling

CSS Variables

:root {
  --yoopta-ui-element-options-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1);
  --yoopta-ui-element-options-content-min-width: 180px;
  --yoopta-ui-element-options-content-padding: 8px;
  --yoopta-ui-element-options-content-radius: 0.5rem;
  --yoopta-ui-element-options-control-padding-y: 6px;
  --yoopta-ui-element-options-control-padding-x: 10px;
  --yoopta-ui-element-options-control-radius: 6px;
  --yoopta-ui-element-options-toggle-width: 36px;
  --yoopta-ui-element-options-toggle-height: 20px;
}

Custom Styling

Apply Tailwind or custom classes to components:

<ElementOptions.Content className="min-w-[200px] rounded-lg border bg-popover p-2 shadow-md">
  <ElementOptions.Group className="flex flex-col gap-1">
    <ElementOptions.Label className="px-2 text-xs font-medium text-muted-foreground">
      Theme
    </ElementOptions.Label>
    <ElementOptions.Select
      className="flex h-8 w-full items-center justify-between rounded-md border px-3 text-sm"
      {...props}
    />
  </ElementOptions.Group>
</ElementOptions.Content>

Best Practices

Separate options into their own component

// Good: Separate component for options
function MyElementOptions() {
  const { element } = useElementOptions();
  const updateProps = useUpdateElementProps();
  // ...
}

// In render:
<ElementOptions.Root blockId={blockId} element={element}>
  <ElementOptions.Trigger />
  <MyElementOptions />
</ElementOptions.Root>

Use group-hover for trigger visibility

<div className="group relative">
  <ElementOptions.Root blockId={blockId} element={element}>
    <ElementOptions.Trigger
      className="absolute right-0 top-0 opacity-0 group-hover:opacity-100 transition-opacity"
    />
    <MyElementOptions />
  </ElementOptions.Root>
  {children}
</div>

Provide default values

// Always provide defaults when reading props
const theme = element.props?.theme ?? 'default';
const enabled = element.props?.enabled ?? false;

BlockOptions

Context menu for block-level actions

FloatingBlockActions

Floating buttons for block operations

Getting Started

Core Concepts

Available Plugins

Marks

UI Components

API Reference

Overview

Features

Installation

Basic Usage

API Reference

`ElementOptions.Root`

`ElementOptions.Trigger`

`ElementOptions.Content`

`ElementOptions.Group`

`ElementOptions.Label`

`ElementOptions.Separator`

`ElementOptions.Select`

`ElementOptions.Toggle`

`ElementOptions.Slider`

`ElementOptions.ColorPicker`

`ElementOptions.Input`

Hooks

`useElementOptions()`

`useUpdateElementProps<T>()`

Examples

Callout Theme Selector

Divider with Style and Color

Table Appearance Toggles

Table of Contents with Input and Toggles

Styling

CSS Variables

Custom Styling

Best Practices

BlockOptions

FloatingBlockActions

Getting Started

Core Concepts

Available Plugins

Marks

UI Components

API Reference

​Overview

​Features

​Installation

​Basic Usage

​API Reference

​ElementOptions.Root

​ElementOptions.Trigger

​ElementOptions.Content

​ElementOptions.Group

​ElementOptions.Label

​ElementOptions.Separator

​ElementOptions.Select

​ElementOptions.Toggle

​ElementOptions.Slider

​ElementOptions.ColorPicker

​ElementOptions.Input

​Hooks

​useElementOptions()

​useUpdateElementProps<T>()

​Examples

​Callout Theme Selector

​Divider with Style and Color

​Table Appearance Toggles

​Table of Contents with Input and Toggles

​Styling

​CSS Variables

​Custom Styling

​Best Practices

​Related Components

BlockOptions

FloatingBlockActions

Overview

Features

Installation

Basic Usage

API Reference

`ElementOptions.Root`

`ElementOptions.Trigger`

`ElementOptions.Content`

`ElementOptions.Group`

`ElementOptions.Label`

`ElementOptions.Separator`

`ElementOptions.Select`

`ElementOptions.Toggle`

`ElementOptions.Slider`

`ElementOptions.ColorPicker`

`ElementOptions.Input`

Hooks

`useElementOptions()`

`useUpdateElementProps<T>()`

Examples

Callout Theme Selector

Divider with Style and Color

Table Appearance Toggles

Table of Contents with Input and Toggles

Styling

CSS Variables

Custom Styling

Best Practices

Related Components