Hooks

Quill Next React provides a set of hooks to help you extend the editor's behavior.

Quill Next provides hooks that are primarily divided into two categories: those used before QuillEditor initialization and those used within QuillEditor plugins. You can clearly distinguish them by their names: all hooks starting with useQuill are intended for use within plugins, such as useQuillFormats(). Conversely, hooks not starting with useQuill should be used before QuillEditor is initialized, such as useReactEmbed.

Initialization Hooks

useEmbedBlot

useEmbedBlot is the most powerful hook, allowing us to easily extend Quill's embed content with React components. With this hook, you can readily implement features like mentions.

import { useEmbedBlot } from "quill-next-react";

const MyEditor = () => {
  const MentionBlot = useEmbedBlot({
    blotName: "mention",
    tagName: "SPAN",
    className: "qn-mention",
    render: (options: IRenderOptions) => {
      return <Mention value={options.value as string} />;
    },
    onAttach: (domNode: HTMLElement) => {
      domNode.style.whiteSpace = "pre-wrap";
      domNode.style.wordBreak = "break-word";
    }
  });
  return (
    <QuillEditor blots={[MentionBlot]}>
    </QuillEditor>
  )
}

blotName

Required: true

The unique name for your custom blot. This name will be used to identify your blot in the editor.

const MyBlot = useEmbedBlot({
  blotName: 'my-custom-blot',
  // ... other props
});

className

Required: true

A CSS class name that Quill will use to identify and match your blot in the editor content. This class name must be unique and consistent. Quill will use this class name to find the blot in the editor content.

const MyBlot = useEmbedBlot({
  className: 'my-custom-blot-class',
  // ... other props
});

render

Required: true

A function that returns the React component to be rendered for your blot. This is where you define how your custom blot should look and behave.

const MyBlot = useEmbedBlot({
  render: () => (
    <div className="my-custom-blot">
      <h3>My Custom Content</h3>
      <p>This is a custom blot rendered with React!</p>
    </div>
  ),
  // ... other props
});

scope

Required: false

Defines the scope of your blot. This determines how the blot behaves in relation to other content in the editor.

const MyBlot = useEmbedBlot({
  scope: BlotScope.BLOCK, // or BlotScope.INLINE
  // ... other props
});

create

Required: false

A function that creates the initial DOM element for your blot. This is useful when you need custom initialization logic.

const MyBlot = useEmbedBlot({
  create: (value) => {
    const node = document.createElement('div');
    node.setAttribute('data-custom-value', value);
    return node;
  },
  // ... other props
});

onAttach

Required: false

A callback function that runs when your blot is attached to the DOM. This is useful for setting up any necessary event listeners or initializations.

const MyBlot = useEmbedBlot({
  onAttach: (domNode) => {
    // Initialize any third-party libraries
    initializeLibrary(domNode);
  },
  // ... other props
});

useNextLinkBlot

useNextLinkBlot is a great example of how Quill Next uses the hook mechanism to extend Quill's functionality. useNextLinkBlot is designed to be used in conjunction with the NotionLinkToolbarPlugin. useNextLinkBlot returns a Blot type that overrides Quill's native Link, while the NotionLinkToolbarPlugin is responsible for displaying a toolbar when the mouse hovers over a link.

useNextImageBlot

Plugin Hooks

useQuill

This hook is the most common hook in the plugin system. It provides access to the quill instance and the quill editor.

const quill = useQuill();

useQuillFormats

useQuillFormats is a highly useful hook when building a custom toolbar using the plugin system. When Quill's selection changes, the formats of the selected text are returned through this hook. If no text is selected, null is returned.

const quill = useQuill();
const formats = useQuillFormats();

return (
  <div className="toolbar">
    <button
      className={classNames({ active: Boolean(formats?.bold) })}
      onClick={() => quill.format('bold', true)}
    >
      Bold
    </button>
  </div>
);

useQuillInput

TODO

useQuillEditorChange

useQuillEditorChange is the combination of useQuillTextChange and useQuillSelectionChange.

The first argument of the callback function is the type of the change. It could be text-change or selection-change.

useQuillEditorChange((type: EditorChangeType, ...args) => {
  console.log(type, ...args);
  // TODO: update the state
});

The function is wrapped to be persistent. So you don't need to use with useCallback.

useQuillTextChange

This hook is used to detect when the user's text changes.

useQuillTextChange((delta: Delta, oldDelta: Delta, source: EmitterSource) => {
  console.log(delta, oldDelta, source);
  // TODO: update the state
});

The function is wrapped to be persistent. So you don't need to use with useCallback.

useQuillSelectionChange

This hook is used to detect when the user's selection changes.

useQuillSelectionChange((range: Range, oldRange: Range, source: EmitterSource) => {
  console.log(range, oldRange, source);
  // TODO: update the state
});

The function is wrapped to be persistent. So you don't need to use with useCallback.

useQuillArrowIndex

TODO

useQuillKeyboardBinding

TODO