DOCSEARCHbyAlgolia
Submit Docs

Remirror Documentation

website·Indexed 34 days ago

https://remirror.io/

A framework for building state-of-the-art rich text editors, providing a set of extensions and hooks for React. Features include a WYSIWYG editor, Markdown and Social editors, and a wide array of extensions such as TableExtension, MentionAtomExtension, and CodeMirrorExtension. Includes guides on installation, manager creation, and migration from v2 to v3.

Tokens
123.3K
Snippets
815
Records
1K
Agent score
68%

What's inside Remirror

  1. Overview of Remirror Extensions

    Extensions in Remirror encapsulate functionality such as keyboard shortcuts, input rules (markdown shortcuts), HTML parsing, and commands. They allow developers to group concerns related to editor display (e.g., bold, italic), command availability, and the registration of ProseMirror plugins, keymaps, and custom nodeViews.

    There are three primary types of extensions:

    • NodeExtension: Used for creating ProseMirror nodes.
    • MarkExtension: Used for creating ProseMirror marks.
    • PlainExtension: Used for behavior that does not require a DOM representation.

  2. Overview of EntityReferenceExtension

    The EntityReferenceExtension allows you to reference external entities within the editor content. This is particularly useful for scenarios where marked text needs to be associated with external metadata, such as linking a piece of text to a specific comment or a highlight with associated tags and colors.

    Comparison to other extensions:

    • Use TextHighlightExtension for simple text highlighting with a color.
    • Use EntityReferenceExtension when the highlighted text requires associated metadata (e.g., comment text, tags).
    • Avoid AnnotationExtension in favor of EntityReferenceExtension due to known issues with annotations.

  3. Overview of AnnotationExtension

    The AnnotationExtension allows users to annotate content within a Remirror editor. Unlike marks, annotations are implemented as decorations, meaning they can span across multiple ProseMirror text nodes without forcing the document model to split. This is particularly useful for maintaining a single identity for a sentence or phrase that may contain multiple formatting marks (e.g., bold and italic).

    Key capabilities include:

    • Overlapping Annotations: Supports partially or fully overlapping annotations, with built-in logic to visualize overlaps by mixing colors.
    • Extendable Data Model: The base model requires only a start position, end position, and an ID. Developers can extend this model to include custom fields like labels or colors, which the extension will pass through to the application.
    • Collaborative Editing: While decorations are typically view-only and not synced, the AnnotationExtension can be integrated with the Yjs extension to utilize a Yjs Map for shared, collaborative annotations.

  4. Overview of Remirror and ProseMirror

    Remirror is an abstraction layer and wrapper library for ProseMirror. While ProseMirror is a powerful toolkit for building rich text editors with a steep learning curve, Remirror simplifies the development process by providing React integration and an extension system. These extensions abstract complex ProseMirror concepts such as schemas, commands, and plugins, allowing developers to either quickly build an out-of-the-box editor or create a highly bespoke editing experience.

  5. Overview of PositionerExtension

    The PositionerExtension is used to track the coordinates and dimensions of different parts of the editor. This allows developers to anchor floating UI elements (like toolbars or menus) to specific locations, such as the current cursor position or visible paragraph nodes.

  6. Overview of CalloutExtension

    The CalloutExtension adds callout functionality to the Remirror editor. It allows users to create highlighted callout blocks (e.g., info, warning, error) using either commands or an input rule triggered by typing three colons followed by a valid callout type.
    import { CalloutExtension } from '@remirror/extension-callout';

// Add to your editor extensions list

  7. Manage whitespace visibility with WhitespaceExtension

    The WhitespaceExtension class allows developers to manage the visibility of whitespace characters within the editor by adding decorators. This is primarily used to increase editor accessibility by making non-printing characters visible.
    import { WhitespaceExtension } from '@remirror/extension-whitespace';

// Add to your Remirror extension list
const extension = new WhitespaceExtension();

  8. Use RemixIcons in @remirror/icons

    The @remirror/icons package provides a collection of icons based on RemixIcons. Each icon is exported as a variable of type IconTree[], which can be used within the Remirror editor framework to render SVG icons.

  9. Update to Remirror v2 pre-packaged components

    In Remirror v2, pre-packaged components (such as the toolbar and buttons) have been revamped. They are now based on the MUI framework instead of Reakit and no longer rely on Remirror-specific infrastructure, making them easier to customize and integrate.

  10. Use DocExtension to define the root document node

    The DocExtension is the default parent node required in the ProseMirror Schema. Every Remirror editor must have a representation of the doc as the top-level node. Note that extra attributes are disallowed for the doc extension; use docAttributes in the options instead.
    import { DocExtension } from '@remirror/extension-doc';

// Basic usage in extensions array
const extensions = [new DocExtension()];

  11. Use EntityReferenceExtension to manage entity references in Remirror

    The EntityReferenceExtension allows you to manage entity references within a Remirror editor. It extends MarkExtension and provides utilities to add, remove, and locate entity references (marks) within the document. Because entity references are stored as marks, a single reference spanning multiple nodes (like paragraphs) is stored as multiple marks with the same ID.
    import { EntityReferenceExtension } from '@remirror/extension-entity-reference';

// Add to your extension list
const extension = new EntityReferenceExtension();

  12. Use MouseEventHandlerState for interaction context

    The MouseEventHandlerState interface provides contextual information about the editor state at the point of a mouse interaction. It is used by click and context menu handlers.

    • view: The current EditorView.
    • nodes: An array of NodeWithPosition. The first element is the node acted on directly; subsequent elements are parents. Use this to determine how to render context menus.
    • marks: An array of GetMarkRange representing marks wrapping the current context.
    • getNode(nodeType): Returns the node with position and an isRoot boolean if the nodeType matches; otherwise returns undefined.
    • getMark(markType): Returns the mark range if it exists for the clicked position.
    interface MouseEventHandlerState {
  view: EditorView;
  nodes: NodeWithPosition[];
  marks: GetMarkRange[];
  getNode: (nodeType: string | NodeType) => (NodeWithPosition & { isRoot: boolean }) | undefined | void;
  getMark: (markType: string | MarkType) => GetMarkRange | undefined | void;
}