Skip to main content

react-core

package @remirror/react-core

function createEditorView()​

Creates a new editor view

Signature:

export declare function createEditorView(place: Node | ((p: HTMLElement) => void) | null, props: DirectEditorProps): EditorView;

Parameters:

ParameterTypeDescription
placeNode | ((p: HTMLElement) => void) | null
propsDirectEditorProps

Returns:

EditorView

function createReactManager()​

Create a React [[RemirrorManager]] with all the default react presets and extensions.

Signature:

export declare function createReactManager<Extension extends AnyExtension>(extensions: Extension[] | (() => Extension[]) | RemirrorManager<ReactExtensions<Extension>>, options?: CreateReactManagerOptions): RemirrorManager<ReactExtensions<Extension>>;

Parameters:

ParameterTypeDescription
extensionsExtension[] | (() => Extension[]) | RemirrorManager<ReactExtensions<Extension>>
optionsCreateReactManagerOptions(Optional)

Returns:

RemirrorManager<ReactExtensions<Extension>>

function Remirror_2()​

[[Remirror]] is the component for putting the editor into into it's child component.

Signature:

export declare function Remirror<Extension extends AnyExtension = Remirror.Extensions>(props: RemirrorProps<Extension>): ReactElement<RemirrorProps<Extension>>;

Parameters:

ParameterTypeDescription
propsRemirrorProps<Extension>

Returns:

ReactElement<RemirrorProps<Extension>>

Remarks:

The main component for remirror. This acts both as a Provider of the remirror context. All components rendered within Remirror have access to the remirror context via useRemirrorContext.

I can also be rendered as a standalone editor without children. In this case the context can be accessed from outside the editor via useRemirror().getContext().

function useActive()​

This is a shorthand method for retrieving the active available in the editor.

import { useActive } from '@remirror/react';

This hooks updates the local component on each state update for the editor, so it can be quite expensive.

Signature:

export declare function useActive<Extension extends AnyExtension = Remirror.Extensions>(autoUpdate?: boolean): ActiveFromExtensions<Extension>;

Parameters:

ParameterTypeDescription
autoUpdateboolean(Optional) Set to false to prevent automatic re-rendering on every state update.

Returns:

ActiveFromExtensions<Extension>

function useAttrs()​

A core hook which provides the attributes for the nodes and marks in the editor.

import { useAttrs } from '@remirror/react';

const EditorButton = () => {
  const attrs = useAttrs();
  const { link } = attrs;

  return <a href={link.href}>{link().href}</a>;
}

Signature:

export declare function useAttrs<Extension extends AnyExtension = Remirror.Extensions>(update?: boolean): AttrsFromExtensions<Extension>;

Parameters:

ParameterTypeDescription
updateboolean(Optional)

Returns:

AttrsFromExtensions<Extension>

function useChainedCommands()​

A core hook which provides the chainable commands for usage in your editor.

import { useChainedCommands } from '@remirror/react';

const EditorButton = () => {
  const chain = useChainedCommands();

  return (
    <>
      <button onClick={() => chain.toggleBold().toggleItalic().run()}>
        Chain me!
      </button>
    </>
  );
}

`

Signature:

export declare function useChainedCommands<Extension extends AnyExtension = Remirror.Extensions | AnyExtension>(): ChainedFromExtensions<Extension>;

Returns:

ChainedFromExtensions<Extension>

function useCommands()​

A core hook which provides the commands for usage in your editor.

import { useCommands } from '@remirror/react';

const EditorButton = () => {
  const commands = useCommands();

  return (
    <>
      <button onClick={() => commands.toggleBold()}>
        Click me!
      </button>
    </>
  );
}

`

Signature:

export declare function useCommands<Extension extends AnyExtension = Remirror.Extensions>(): CommandsFromExtensions<Extension>;

Returns:

CommandsFromExtensions<Extension>

function useCurrentSelection()​

A core hook which returns the current selection.

Signature:

export declare function useCurrentSelection(): Selection;

Returns:

Selection

function useDocChanged()​

A hook for subscribing to transactions that change the document

Signature:

export declare function useDocChanged(handler: NonNullable<GetHandler<DocChangedOptions>['docChanged']>): void;

Parameters:

ParameterTypeDescription
handlerNonNullable<GetHandler<DocChangedOptions>['docChanged']>

Returns:

void

function useEditorDomRef()​

A hook which provides a react ref wrapper for the view.dom.

Signature:

export declare function useEditorDomRef(): MutableRefObject<HTMLElement>;

Returns:

MutableRefObject<HTMLElement>

function useEditorState()​

A core hook which provides the latest editor state every time that it updates.

Signature:

export declare function useEditorState(): EditorState;

Returns:

EditorState

function useEditorView()​

A hook which provides access to the editor view.

Signature:

export declare function useEditorView(): EditorView;

Returns:

EditorView

function useExtension()​

Dynamically update the properties of your extension via hooks. Provide the Extension constructor and the properties you want to update.

Signature:

export declare function useExtension<Type extends AnyExtensionConstructor>(Constructor: Type): InstanceType<Type>;

Parameters:

ParameterTypeDescription
ConstructorType

Returns:

InstanceType<Type>

Remarks:

Please note that every time the properties change your extension is updated. You will want to memoize or prevent needless updates somehow to the properties passed in.

This is only available within the context of the Remirror it will throw an error otherwise.

It can be used with three distinct call signatures.

**Get the extension instance**

import { useExtension } from '@remirror/react';
import { BoldExtension } from 'remirror/extensions';

const Editor = () => {
  const boldExtension = useExtension(BoldExtension);

  boldExtension.setOptions({ weight: '800' });

  return null;
}

**Update the extension properties**

import { useExtension } from '@remirror/react';
import { PlaceholderExtension } from 'remirror/extensions';

const EditorPlaceholder = ({ placeholder = 'Your magnum opus' }) => {
  useExtension(PlaceholderExtension, { placeholder }); // Updates the placeholder.

  return null;
}

**Add event handlers to your extension**

import { useCallback } from 'react';
import { HistoryExtension, HistoryOptions } from 'remirror/extensions';
import { useExtension } from '@remirror/react';

const Editor = ({ placeholder = 'Your magnum opus' }) => {
  useExtension(
    HistoryExtension,
    useCallback(
      ({ addHandler }) => {
        return addHandler('onRedo', () => log('a redo just happened'));
      },
      [],
    ),
    [event, handler],
  );

  return null;
};

These hooks can serve as the building blocks when customizing your editor experience with remirror.

function useExtension()​

Signature:

export declare function useExtension<Type extends AnyExtensionConstructor>(Constructor: Type, memoizedCallback: UseExtensionCallback<Type>, dependencies?: DependencyList): void;

Parameters:

ParameterTypeDescription
ConstructorType
memoizedCallbackUseExtensionCallback<Type>
dependenciesDependencyList(Optional)

Returns:

void

function useExtension()​

Signature:

export declare function useExtension<Type extends AnyExtensionConstructor>(Constructor: Type, options: DynamicOptionsOfConstructor<Type>): void;

Parameters:

ParameterTypeDescription
ConstructorType
optionsDynamicOptionsOfConstructor<Type>

Returns:

void

function useExtensionEvent()​

Dynamically add event handlers to your extension.

Signature:

export declare function useExtensionEvent<Type extends AnyExtensionConstructor, Key extends keyof GetHandler<OptionsOfConstructor<Type>>>(extension: Type, event: Key, memoizedHandler: Handler<GetHandler<OptionsOfConstructor<Type>>[Key]>): void;

Parameters:

ParameterTypeDescription
extensionType
eventKey
memoizedHandlerHandler<GetHandler<OptionsOfConstructor<Type>>[Key]>

Returns:

void

Remarks:

Please note that every time the properties change your extension is updated. You will want to memoize or prevent needless updates somehow to the properties passed in.

This is only available within the context of the Remirror it will throw an error otherwise.

import { useCallback } from 'react';
import { HistoryExtension } from 'remirror/extensions';
import { useExtensionEvent } from '@remirror/react';

const RedoLogger = () => {
  useExtensionEvent(
    HistoryExtension,
    'onRedo',
    useCallback(() => log('a redo just happened'), []),
  );

  return null;
};

These hooks can serve as the building blocks when customizing your editor experience with remirror.

function useHasExtension()​

Assert if an extension is present in the manager by providing its constructor

Signature:

export declare function useHasExtension<Type extends AnyExtensionConstructor>(Constructor: Type): boolean;

Parameters:

ParameterTypeDescription
ConstructorType

Returns:

boolean

function useHelpers()​

A core hook which provides the helpers for usage in your editor.

import { useHelpers } from '@remirror/react';

const EditorButton = () => {
  const helpers = useHelpers();

  return (
    <>
      <button onClick={() => helpers.toggleBold()}>
        Click me!
      </button>
      <button onClick={() => helpers.chain.toggleBold().toggleItalic().run()}>
        Chain me!
      </button>
    </>
  );
}

`

Passing true as the first argument will ensure that the component this hook is placed inside will rerender on every update.

Signature:

export declare function useHelpers<Extension extends AnyExtension = Remirror.Extensions>(update?: boolean): HelpersFromExtensions<Extension>;

Parameters:

ParameterTypeDescription
updateboolean(Optional)

Returns:

HelpersFromExtensions<Extension>

function useI18n()​

Signature:

export declare function useI18n(): UseI18nReturn;

Returns:

UseI18nReturn

function useMarkRange()​

A hook which returns the selected range of the mark of the provided type.

Signature:

export declare function useMarkRange(type: string): GetMarkRange | undefined;

Parameters:

ParameterTypeDescription
typestring

Returns:

GetMarkRange | undefined

function usePortalContainer()​

A hook which provides access to the portal container for rendering react component directly within the editor dom.

Signature:

export declare function usePortalContainer(): PortalContainer;

Returns:

PortalContainer

function useRemirror()​

A hook which replaces the [[Remirror]] and gives you total control of the editor you can create.

This is very experimental and if successful could replace the current patterns being used.

Signature:

export declare function useRemirror<Extension extends AnyExtension>(props?: UseRemirrorProps<Extension>): UseRemirrorReturn<ReactExtensions<Extension>>;

Parameters:

ParameterTypeDescription
propsUseRemirrorProps<Extension>(Optional)

Returns:

UseRemirrorReturn<ReactExtensions<Extension>>

function useRemirrorContext()​

This provides access to the remirror context when using the Remirror.

The first argument which is optional can also be a change handler which is called every time the state updates.

Signature:

export declare function useRemirrorContext<Extension extends AnyExtension = Remirror.Extensions>(handler?: RemirrorEventListener<Extension> | {
    autoUpdate: boolean;
}): ReactFrameworkOutput<Extension>;

Parameters:

ParameterTypeDescription
handlerRemirrorEventListener<Extension> | { autoUpdate: boolean; }(Optional)

Returns:

ReactFrameworkOutput<Extension>

Remarks:

The following example applies the root props to the div.

import { Remirror, useRemirrorContext } from 'remirror';

const HooksComponent = (props) => {
  // This pulls the remirror props out from the context.
  const { getRootProps } = useRemirrorContext();

  return <div {...getRootProps()} />;
}

class App extends Component {
  render() {
    return (
      <Remirror>
        <HooksComponent />
      </Remirror>
    );
  }
}

For performance reasons useRemirror does not automatically trigger a rerender on every editor update. This allows for you use it in component which don't need to track the latest editor state, without suffering a performance penalty.

However if you do want to track whether a command is enabled at the current selection or whether a certain formatting mark (bold) is active at the current selection you can pass through an optional parameter.

const EditorButton = () => {
  const { active, commands } = useRemirrorContext({ autoUpdate: true });

  return (
    <button style={{ fontWeight: active.bold() ? 'bold' : undefined }}>
      B
    <button>
  );
}

The above example keep track of whether the current selection is bold on every update to the editor. Updates can be document changes and selection changes.

For more control you can also use a handler function as the first parameter to selectively rerender as you see fit.

const EditorButton = () => {
  const { active, commands } = useRemirrorContext(() => {
    if (active.bold() === boldActive) {
      return;
    }

    setBoldActive(active.bold());
  });

  const [boldActive, setBoldActive] = useState(active.bold());

  return (
    <button style={{ fontWeight: boldActive ? 'bold' : undefined }}>
      B
    <button>
  )
}

In this case the component only re-renders when the bold formatting changes.

function useSelectedText()​

A core hook which provides the the currently selected text.

import { useSelectedText } from '@remirror/react';

const RandomSpan = () => {
  const text = useSelectedText();

  return text  && <span>{text}</span>;
}

`

Return the value of the currently selected text. When the text selection is empty

Signature:

export declare function useSelectedText(): string | undefined;

Returns:

string | undefined

function useUpdateReason()​

Provide the reason for the latest state update with boolean flags.

Signature:

export declare function useUpdateReason(): UpdateReason;

Returns:

UpdateReason

variable EditorComponent​

The default editor placeholder where the prosemirror editor will be rendered.

Signature:

EditorComponent: () => JSX.Element

variable I18nProvider​

Signature:

I18nProvider: FC<I18nProps>

variable OnChangeHTML​

Signature:

OnChangeHTML: ({ onChange }: OnChangeHTMLProps) => null

variable OnChangeJSON​

Signature:

OnChangeJSON: ({ onChange }: OnChangeJSONProps) => null

variable RemirrorContext​

The ReactContext for the Remirror editor.

Signature:

RemirrorContext: import("react").Context<ReactFrameworkOutput<any> | null>

interface CreateReactManagerOptions​

The options for the exported createReactManager method.

Signature:

export interface CreateReactManagerOptions extends CreateCoreManagerOptions

Extends: CreateCoreManagerOptions

(Some inherited members may not be shown because they are not represented in the documentation.)

property react​

Options for the react preset.

Signature:

react?: GetStaticAndDynamic<ReactExtensionOptions>;

interface GetRootPropsConfig​

The config options for the getRootProps method.

Signature:

export interface GetRootPropsConfig<RefKey extends string = 'ref'> extends RefProps<RefKey>, Shape

Extends: RefProps<RefKey>, Shape

property ref​

Allows for composing the refs together. If you have a ref you would also like to add to the main element then just add it here.

Signature:

ref?: Ref<HTMLElement>;

property refKey​

A custom ref key which allows a reference to be obtained from non standard components.

Signature:

refKey?: RefKey;

Signature:

[key: string]: any;

interface I18nProps​

Signature:

export interface I18nProps

property children​

Signature:

children?: ReactNode;

property i18nFormat​

Provide a function that formats ICU MessageFormat encoded messages, via your chosen i18n solution.

You can use the i18nFormat function from the optional @remirror/i18n library, which is powered by Lingui

import { i18nFormat } from '@remirror/i18n';

const Editor = () => {
  <Remirror i18nFormat={i18nFormat} />
}

Signature:

i18nFormat?: I18nFormatter;

property locale​

The current locale for this context.

Signature:

locale?: string;

property supportedLocales​

Supported locales. Defaults to including the locale.

Signature:

supportedLocales?: string[];

interface OnChangeHTMLProps​

Signature:

export interface OnChangeHTMLProps

property onChange​

Signature:

onChange: (html: string) => void;

interface OnChangeJSONProps​

Signature:

export interface OnChangeJSONProps

property onChange​

Signature:

onChange: (json: RemirrorJSON) => void;

interface ReactFrameworkOutput​

These are the props passed to the render function provided when setting up your editor.

Signature:

export interface ReactFrameworkOutput<Extension extends AnyExtension> extends FrameworkOutput<Extension>

Extends: FrameworkOutput<Extension>

(Some inherited members may not be shown because they are not represented in the documentation.)

property getRootProps​

A function that returns the props which should be spread on the react element to be used as the root for the editor. This is where the ProseMirror editor is injected into the DOM).

Signature:

getRootProps: <RefKey extends string = 'ref'>(options?: GetRootPropsConfig<RefKey>) => RefKeyRootProps<RefKey>;

Remarks:

By default Remirror will add the prosemirror editor instance directly into the first child element it receives. Using this method gives you full control over where the editor should be injected.

**IMPORTANT** In order to support SSR pre-rendering this should only be spread on a component with NO children.

**Example with indirectly nested components**

import { Remirror } from '@remirror/react';
import { PresetCore } from '@remirror/preset-core';
import { BoldExtension } from '@remirror/extension-bold';

const InnerEditor = () => {
  const { getRootProps } = useRemirror();
  return <div {...getRootProps()} />;
}

const EditorWrapper = () => {
  const corePreset = usePreset(CorePreset);
  const boldExtension = useExtension(BoldExtension);
  const manager = useManager([corePreset, boldExtension]);

  return (
    <Remirror manager={manager}>
      <InnerEditor />
    </Remirror>
  );
}

interface RefProps​

Signature:

export interface RefProps<RefKey = 'ref'>

property refKey​

A custom ref key which allows a reference to be obtained from non standard components.

Signature:

refKey?: RefKey;

interface RemirrorProps​

The props for the main <Remirror /> component.

Signature:

export interface RemirrorProps<Extension extends AnyExtension = Remirror.Extensions> extends Omit<ReactFrameworkProps<Extension>, 'stringHandler' | 'manager'>, I18nProps

Extends: Omit<ReactFrameworkProps<Extension>, 'stringHandler' | 'manager'>, I18nProps

(Some inherited members may not be shown because they are not represented in the documentation.)

property autoRender​

Set this to start or end to automatically render the editor to the dom.

When set to start the editor will be added before all other child components. If end the editable editor will be added after all child components.

When no children are provided the editor will automatically be rendered even without this prop being set.

start is the preferred value since it helps avoid some of the issues that can arise from zIndex issues with floating components rendered within the context.

Signature:

autoRender?: boolean | 'start' | 'end';

property children​

The optional children which can be passed into the [Remirror].

Signature:

children?: ReactNode;

property hooks​

An array of hooks that can be passed through to the Remirror component and will be called in the order provided. Each hook receives no props but will have access to the RemirrorContext.

If you'd like access to more state, you can wrap the Remirror component in a custom provider and attach your state there. It can then be accessed inside the hook via context.

Signature:

hooks?: Array<() => void>;

property i18nFormat​

Provide a function that formats ICU MessageFormat encoded messages, via your chosen i18n solution.

You can use the i18nFormat function from the optional @remirror/i18n library, which is powered by Lingui

import { i18nFormat } from '@remirror/i18n';

const Editor = () => {
  <Remirror i18nFormat={i18nFormat} />
}

Signature:

i18nFormat?: I18nFormatter;

property locale​

The current locale for this context.

Signature:

locale?: string;

property manager​

This manager composes the extensions provided and provides the functionality used throughout the editor.

It is overridden here since there was an issue with type inference when using the manager inherited from ReactFrameworkProps.

Signature:

manager: RemirrorManager<any>;

property supportedLocales​

Supported locales. Defaults to including the locale.

Signature:

supportedLocales?: string[];

interface UpdateReason​

Signature:

export interface UpdateReason

property doc​

The document changed.

Signature:

doc: boolean;

property selection​

The selection changed.

Signature:

selection: boolean;

property storedMark​

A stored mark was added to the current selection

Signature:

storedMark: boolean;

interface UseRemirrorProps​

Props which are passed into the useRemirror hook.

Signature:

export interface UseRemirrorProps<Extension extends AnyExtension> extends CreateReactManagerOptions, Partial<CreateEditorStateProps>

Extends: CreateReactManagerOptions, Partial<CreateEditorStateProps>

(Some inherited members may not be shown because they are not represented in the documentation.)

property extensions​

Provide a function that returns an array of extensions which will be used to create the manager. If you prefer you can directly provide your own RemirrorManager to override this. The manager you provide will be cloned and used within your editor.

When a Manager is provided then several settings are ignored like [[stringHandler]] and [[onError]].

Signature:

extensions?: (() => Extension[]) | RemirrorManager<any>;

property onError​

This is called when the editor has invalid content.

Signature:

onError?: InvalidContentHandler;

Remarks:

To add this to the editor the following is needed.

import React from 'react';
import { Remirror, InvalidContentHandler } from 'remirror';
import { Remirror, useManager } from '@remirror/react';
import { WysiwygPreset } from 'remirror/extensions';

const Framework = () => {
  const onError: InvalidContentHandler = useCallback(({ json, invalidContent, transformers }) => {
    // Automatically remove all invalid nodes and marks.
    return transformers.remove(json, invalidContent);
  }, []);

  const manager = useManager(() => [new WysiwygPreset()]);

  return (
    <Remirror manager={manager} onError={onError}>
      <div />
    </Remirror>
  );
};

property react​

Options for the react preset.

Signature:

react?: GetStaticAndDynamic<ReactExtensionOptions>;

property stringHandler​

A function which transforms a string into a prosemirror node.

Signature:

stringHandler?: keyof Remirror.StringHandlers | StringHandler;

Remarks:

Can be used to transform markdown / html or any other string format into a prosemirror node.

See [[fromHTML]] for an example of how this could work.

interface UseRemirrorReturn​

Signature:

export interface UseRemirrorReturn<Extension extends AnyExtension>

property getContext​

A function that provides the editor context. This is only available after the <Remirror /> component is mounted. Calling it in the very first render phase will cause an error to be thrown.

Signature:

getContext: () => ReactFrameworkOutput<Extension> | undefined;

property manager​

The manager which is required by the <Remirror /> component.

Signature:

manager: RemirrorManager<Extension>;

property onChange​

Syntactic sugar for using the setState method directly on the `

` component.

import React from 'react';
import { useRemirror, Provider } from '@remirror/react';
import { htmlToProsemirrorNode } from 'remirror';

const Editor = () => {
  const { manager, onChange, state } = useRemirror({
    content: '<p>Some content</p>',
    stringHandler: htmlToProsemirrorNode
  });

  return <Remirror onChange={onChange} state={state} manager={manager} />
}

Signature:

onChange: RemirrorEventListener<Extension>;

property setState​

A function to update the state when you intend to make the editor controlled.

import React, { useCallback } from 'react';
import { useRemirror, Provider } from '@remirror/react';
import { htmlToProsemirrorNode } from 'remirror';

const Editor = () => {
  const { manager, setState, state } = useRemirror({
    content: '<p>Some content</p>',
    stringHandler: htmlToProsemirrorNode
  });

  return (
    <Remirror
      onChange={useCallback((changeProps) => setState(changeProps.state), [setState])}
      state={state}
      manager={manager}
    />
  );
}

Signature:

setState: (state: EditorState) => void;

property state​

The initial editor state based on the provided content and selection properties. If none were passed in then the state is created from the default empty doc node as defined by the editor Schema.

Signature:

state: EditorState;

type ReactExtensions​

Use this to build your own extension union type which extends from the ReactExtensions.

Signature:

export type ReactExtensions<Extension extends AnyExtension = never> = CorePreset | ReactExtension | BuiltinPreset | Extension;

type RefKeyRootProps​

The react ref key props for the getRootProps method.

Signature:

export type RefKeyRootProps<RefKey extends string = 'ref'> = {
    [P in Exclude<RefKey, 'key'>]: Ref<any>;
} & {
    key: string;
    children: ReactNode;
} & Shape;

References: Shape

type UseExtensionCallback​

Signature:

export type UseExtensionCallback<Type extends AnyExtensionConstructor> = (props: UseExtensionCallbackProps<Type>) => Dispose | undefined;

References: Dispose

type UseI18nReturn​

Signature:

export type UseI18nReturn = I18nFormatter;

References: I18nFormatter

type UseRemirrorContextType​

This is a type alias for creating your own typed version of the remirror method.

import { useRemirror, UseRemirrorContextType } from '@remirror/react';
import { SocialPreset } from 'remirror/extensions'

const useSocialRemirror = useRemirror as UseRemirrorContextType<SocialPreset>;

// With the remirror provider context.
const Editor = () => {
  const { commands } = useSocialRemirror();

  // All available commands are shown with intellisense. Command click to goto the implementation.
  commands.toggleBold();
}

Signature:

export type UseRemirrorContextType<Extension extends AnyExtension> = <Type extends AnyExtension>(handler?: RemirrorEventListener<Extension> | {
    autoUpdate: boolean;
}) => ReactFrameworkOutput<Extension | Type>;

References: ReactFrameworkOutput