TheodoreRef

The Theodore component accepts a theodoreRef prop that exposes imperative methods through the TheodoreHandle type. Use it when code outside the editor needs to update the editor directly, such as an emoji picker, saved draft loader, or send button.

This example creates a ref for the editor, passes it to Theodore, then uses external buttons to insert an emoji or reset the editor.

import { useRef } from 'react';
import { Theodore, type TheodoreHandle, useEditorState } from 'theodore-js';
 
export function MessageInput() {
  const editorState = useEditorState();
  const theodoreRef = useRef<TheodoreHandle>(null);
 
  return (
    <>
      <Theodore
        editorState={editorState}
        renderEmoji={(emoji) => <img src={`/emoji/${emoji}.png`} alt={emoji} />}
        theodoreRef={theodoreRef}
      />
 
      <button type="button" onClick={() => theodoreRef.current?.insertEmoji('😂')}>
        Insert emoji
      </button>
 
      <button type="button" onClick={() => theodoreRef.current?.resetEditor()}>
        Clear
      </button>
    </>
  );
}

insertEmoji(emoji)

insertEmoji: (emoji: string) => void;

Inserts an emoji at the current editor selection. If the user has selected a range, Theodore replaces that selection with the inserted emoji node.

The string you pass to insertEmoji is forwarded to your renderEmoji function, so use the same value format that your renderer expects. For example, if renderEmoji maps native emoji characters to image paths, pass the native emoji character:

theodoreRef.current?.insertEmoji('😂');

You can use this method to insert emoji into editor from external emoji pickers or custom toolbar buttons.

setContent(content)

setContent: (content: string) => void;

Replaces the current editor content with the provided plain text string.

theodoreRef.current?.setContent('Hello 😂');

Use setContent when loading a draft, resetting the editor after a message is sent, or applying content from another part of your UI. Passing an empty string clears the editor:

theodoreRef.current?.setContent('');

Theodore parses the provided text into its internal editor nodes. Emoji characters in the string are rendered through your renderEmoji function, the same as emoji typed or pasted by the user. After setting content, Theodore moves the selection to the end of the inserted content.

acceptSuggestion()

acceptSuggestion: () => void;

Accepts the current suggestion and converts it into regular editor content. If there is no active suggestion, this method does nothing.

Call acceptSuggestion from your own interaction handler when the user indicates that they want to accept the suggestion—for example, by pressing Tab on desktop or Enter on mobile.

After accepting a suggestion, stop passing it through the suggestion prop. You can either remove the prop value or replace it with a new suggestion.

rejectSuggestion()

rejectSuggestion: () => void;

Rejects and removes the current suggestion without adding it to the editor content. If there is no active suggestion, this method does nothing.

Call rejectSuggestion from your own interaction handler when the user dismisses the suggestion—for example, by pressing Escape on desktop. After rejecting a suggestion, stop passing it through the suggestion prop. You can either remove the prop value or replace it with a new suggestion.

resetEditor()

resetEditor: () => void;

Clears the editor content and resets its undo history. Use resetEditor when the previous content should no longer be recoverable—for example, after a message has been sent.

This method differs from calling setContent(''), which clears the content but preserves the undo history. After setContent(''), the user can still restore the previous content by pressing Ctrl+Z.