tessl/npm-udecode--plate-list

List plugin for Plate rich-text editor providing indent-based list functionality with comprehensive transforms, queries, and React hooks.

—

Pending

Overview

Eval results

Files

React Hooks

Name: tessl/npm-udecode--plate-list
Author: tessl

React hooks for building list UI components and toolbar buttons. These hooks provide the state management and event handling needed for list-related UI components.

Capabilities

useListToolbarButtonState

State hook for list toolbar button that tracks whether the current selection contains lists of a specific type.

/**
 * State hook for list toolbar button
 * @param options - Configuration including node type
 * @returns State object with nodeType and pressed status
 */
function useListToolbarButtonState(options?: {
  nodeType?: string;
}): {
  nodeType: string;
  pressed: boolean;
};

Usage Example:

import { useListToolbarButtonState, ListStyleType } from "@udecode/plate-list/react";

function BulletListButton() {
  const state = useListToolbarButtonState({
    nodeType: ListStyleType.Disc
  });
  
  // state.pressed will be true if selection contains bullet lists
  return <button className={state.pressed ? 'active' : ''}>{/* ... */}</button>;
}

useListToolbarButton

Behavior hook for list toolbar button that provides click handlers and props for toggling list formatting.

/**
 * Behavior hook for list toolbar button
 * @param state - State from useListToolbarButtonState
 * @returns Props object with event handlers
 */
function useListToolbarButton(
  state: ReturnType<typeof useListToolbarButtonState>
): {
  props: {
    pressed: boolean;
    onClick: () => void;
    onMouseDown: (e: React.MouseEvent<HTMLButtonElement>) => void;
  };
};

Complete Usage Example:

import { 
  useListToolbarButtonState, 
  useListToolbarButton,
  ListStyleType 
} from "@udecode/plate-list/react";

function BulletListToolbarButton() {
  const state = useListToolbarButtonState({
    nodeType: ListStyleType.Disc
  });
  const { props } = useListToolbarButton(state);
  
  return (
    <button {...props}>
      Bullet List
    </button>
  );
}

function NumberedListToolbarButton() {
  const state = useListToolbarButtonState({
    nodeType: ListStyleType.Decimal
  });
  const { props } = useListToolbarButton(state);
  
  return (
    <button {...props}>
      Numbered List
    </button>
  );
}

useTodoListElementState

State hook for todo list element that manages checkbox state and editor context.

/**
 * State hook for todo list element
 * @param options - Configuration including element
 * @returns State object with checkbox status and editor context
 */
function useTodoListElementState(options: {
  element: TElement;
}): {
  checked: boolean;
  editor: PlateEditor;
  element: TElement;
  readOnly: boolean;
};

useTodoListElement

Behavior hook for todo list element that provides checkbox props and change handlers.

/**
 * Behavior hook for todo list element
 * @param state - State from useTodoListElementState
 * @returns Checkbox props object with event handlers
 */
function useTodoListElement(
  state: ReturnType<typeof useTodoListElementState>
): {
  checkboxProps: {
    checked: boolean;
    onCheckedChange: (value: boolean) => void;
    onMouseDown: (e: any) => void;
  };
};

Complete Usage Example:

import {
  useTodoListElementState,
  useTodoListElement
} from "@udecode/plate-list/react";
import { PlateRenderElementProps } from "@udecode/plate/react";

function TodoListElement({ element, children }: PlateRenderElementProps) {
  const state = useTodoListElementState({ element });
  const { checkboxProps } = useTodoListElement(state);
  
  return (
    <div className="todo-list-item">
      <input
        type="checkbox"
        {...checkboxProps}
      />
      <span className={checkboxProps.checked ? 'completed' : ''}>
        {children}
      </span>
    </div>
  );
}

useIndentTodoToolBarButtonState

State hook for todo list toolbar button that tracks todo list presence in selection.

/**
 * State hook for todo list toolbar button
 * @param options - Configuration including node type
 * @returns State object with nodeType and pressed status
 */
function useIndentTodoToolBarButtonState(options?: {
  nodeType?: string;
}): {
  nodeType: string;
  pressed: boolean;
};

useIndentTodoToolBarButton

Behavior hook for todo list toolbar button that provides click handlers for toggling todo list formatting.

/**
 * Behavior hook for todo list toolbar button
 * @param state - State from useIndentTodoToolBarButtonState
 * @returns Props object with event handlers
 */
function useIndentTodoToolBarButton(
  state: ReturnType<typeof useIndentTodoToolBarButtonState>
): {
  props: {
    pressed: boolean;
    onClick: () => void;
    onMouseDown: (e: React.MouseEvent<HTMLButtonElement>) => void;
  };
};

Usage Example:

import {
  useIndentTodoToolBarButtonState,
  useIndentTodoToolBarButton,
  ListStyleType
} from "@udecode/plate-list/react";

function TodoListToolbarButton() {
  const state = useIndentTodoToolBarButtonState({
    nodeType: ListStyleType.Disc
  });
  const { props } = useIndentTodoToolBarButton(state);
  
  return (
    <button {...props}>
      Todo List
    </button>
  );
}

Hook Patterns

Building Complete Toolbar

import {
  useListToolbarButtonState,
  useListToolbarButton,
  useIndentTodoToolBarButtonState,
  useIndentTodoToolBarButton,
  ListStyleType
} from "@udecode/plate-list/react";

function ListToolbar() {
  // Bullet list button
  const bulletState = useListToolbarButtonState({
    nodeType: ListStyleType.Disc
  });
  const { props: bulletProps } = useListToolbarButton(bulletState);
  
  // Numbered list button
  const numberedState = useListToolbarButtonState({
    nodeType: ListStyleType.Decimal
  });
  const { props: numberedProps } = useListToolbarButton(numberedState);
  
  // Todo list button
  const todoState = useIndentTodoToolBarButtonState();
  const { props: todoProps } = useIndentTodoToolBarButton(todoState);
  
  return (
    <div className="list-toolbar">
      <button {...bulletProps}>• Bullets</button>
      <button {...numberedProps}>1. Numbers</button>
      <button {...todoProps}>☐ Todo</button>
    </div>
  );
}

Building Custom List Components

import { 
  useTodoListElementState,
  useTodoListElement
} from "@udecode/plate-list/react";
import { PlateRenderElementProps } from "@udecode/plate/react";

function CustomTodoListElement({ element, children }: PlateRenderElementProps) {
  const state = useTodoListElementState({ element });
  const { checkboxProps } = useTodoListElement(state);
  
  return (
    <div className={`todo-item ${state.readOnly ? 'readonly' : ''}`}>
      <label className="todo-checkbox-container">
        <input
          type="checkbox"
          className="todo-checkbox"
          {...checkboxProps}
          disabled={state.readOnly}
        />
        <span className="checkmark"></span>
      </label>
      <div className={`todo-content ${checkboxProps.checked ? 'completed' : ''}`}>
        {children}
      </div>
    </div>
  );
}

Conditional Rendering Based on List State

import { useListToolbarButtonState, ListStyleType } from "@udecode/plate-list/react";

function SmartListControls() {
  const bulletState = useListToolbarButtonState({
    nodeType: ListStyleType.Disc
  });
  const numberedState = useListToolbarButtonState({
    nodeType: ListStyleType.Decimal
  });
  
  const hasAnyList = bulletState.pressed || numberedState.pressed;
  
  return (
    <div>
      {/* Always show list creation buttons */}
      <ListCreationButtons />
      
      {/* Only show indentation controls when in a list */}
      {hasAnyList && <IndentationControls />}
    </div>
  );
}

State Management

Hook State Flow

State Hooks (useListToolbarButtonState, useTodoListElementState) query the editor and return current state
Behavior Hooks (useListToolbarButton, useTodoListElement) provide event handlers that modify editor state
State changes trigger re-renders with updated state from state hooks

Editor Integration

All hooks integrate with the Plate editor through:

useEditorRef() - Gets current editor instance
useEditorSelector() - Subscribes to editor state changes
useReadOnly() - Respects editor read-only state

Performance Considerations

State hooks use useEditorSelector for efficient re-rendering
Only re-render when relevant editor state changes
Event handlers are memoized to prevent unnecessary re-renders

Install with Tessl CLI

npx tessl i tessl/npm-udecode--plate-list

docs