react-hooks

package @remirror/react-hooks

function indexFromArrowPress()

Get the next index from an arrow key press.

Signature:

export declare function indexFromArrowPress({ direction, matchLength, previousIndex, }: IndexFromArrowPressProps): number;

Parameters:

Parameter	Type	Description
{ direction, matchLength, previousIndex, }	IndexFromArrowPressProps

Returns:

number

function useEditorEvent()

A hook for subscribing to events from the editor.

Signature:

export declare function useEditorEvent<Key extends StringKey<GetHandler<EventsOptions>>>(event: Key, handler: NonNullable<GetHandler<EventsOptions>[Key]>): void;

Parameters:

Parameter	Type	Description
event	Key
handler	NonNullable<GetHandler<EventsOptions>[Key]>

Returns:

void

function useEditorFocus()

Keep track of the editor focus.

Returns a focused value which is updated whenever the editor focus changes.

When true, the editor is focused when false the editor is not focused.

Signature:

export declare function useEditorFocus(props?: UseEditorFocusProps): [isFocused: boolean, focus: (position?: FocusType) => void];

Parameters:

Parameter	Type	Description
props	UseEditorFocusProps	(Optional)

Returns:

[isFocused: boolean, focus: (position?: FocusType) => void]

function useEmoji()

This hook provides the state for setting up an emoji state change handler. It applies the keybindings and the required change handlers.

Signature:

export declare function useEmoji(props?: UseEmojiProps): UseEmojiReturn;

Parameters:

Parameter	Type	Description
props	UseEmojiProps	(Optional)

Returns:

UseEmojiReturn

function useHistory()

A hook which is called every time an undo or redo event is triggered from within the ProseMirror history extension.

Signature:

export declare function useHistory<Key extends StringKey<GetHandler<HistoryOptions>>>(event: Key, handler: NonNullable<GetHandler<HistoryOptions>[Key]>): void;

Parameters:

Parameter	Type	Description
event	Key
handler	NonNullable<GetHandler<HistoryOptions>[Key]>

Returns:

void

Remarks:

handler should be a memoized function.

function useHover()

A hook which listens to hover events.

Provide a memoized handler which is provided with the nodes which were directly touched by the hover: true or hover: false event.

Signature:

export declare function useHover(handler: HoverEventHandler): void;

Parameters:

Parameter	Type	Description
handler	HoverEventHandler

Returns:

void

function useKeymap()

Add custom keyboard bindings to the editor instance.

Signature:

export declare function useKeymap(name: LiteralUnion<KeyBindingNames, string>, handler: KeyBindingCommandFunction, priority?: ExtensionPriority): void;

Parameters:

Parameter	Type	Description
name	LiteralUnion<KeyBindingNames, string>
handler	KeyBindingCommandFunction
priority	ExtensionPriority	(Optional)

Returns:

void

Remarks:

import { useCallback } from 'react';
import { BoldExtension } from 'remirror/extensions';
import { Remirror, useHelpers, useKeymap, useRemirror, useRemirrorContext } from '@remirror/react';

const hooks = [
  () => {
    const active = useActive();
    const { insertText } = useCommands();
    const boldActive = active.bold();
    const handler = useCallback(() => {
      if (!boldActive) {
        return false;
      }

      // Prevent the keypress from using the default action.
      return insertText.original('\n\nWoah there!')(props);
    }, [boldActive, insertText]);

    useKeymap('Shift-Enter', handler); // Add the handler to the keypress pattern.
  },
];

const Editor = () => {
  const { manager } = useRemirror({ extensions: () => [new BoldExtension()] });

  return <Remirror manager={manager} hooks={hooks} />;
};

function useKeymaps()

Add custom keyboard bindings to the editor instance.

Signature:

export declare function useKeymaps(bindings: KeyBindings, priority?: ExtensionPriority): void;

Parameters:

Parameter	Type	Description
bindings	KeyBindings
priority	ExtensionPriority	(Optional)

Returns:

void

Remarks:

import { Remirror, useRemirror, useRemirrorContext, useKeymaps  } from '@remirror/react';

const Editor = () => {
  const { manager } = useRemirror({ extensions: () => [] });

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

const EditorBindings = () => {
  const { getRootProps } = useRemirrorContext({ autoUpdate: true });

  useKeymaps({
    Enter: () => {
      // Prevent the tne enter key from being pressed.
      return true;
    }
  });

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

function useMention()

A hook that provides the state for social mentions that responds to keybindings and key-presses from the user.

This is used by the SocialMentionDropdown component and can be used by you for a customized component.

The only prop required is the list of data in order to support keybinding and properly selecting the index for you. The data must have a label and id key. The label is the text that should be shown inside the mention and the id is whatever unique identifier that can be used.

You can also add other supported attributes which will be added to the mention node, like href and whatever you decide.

Signature:

export declare function useMention<Data extends MentionExtensionAttributes = MentionExtensionAttributes>(props: UseMentionProps<Data>): UseMentionReturn<Data>;

Parameters:

Parameter	Type	Description
props	UseMentionProps<Data>

Returns:

UseMentionReturn<Data>

function useMentionAtom()

A hook that provides the state for social mention atoms that responds to keybindings and key-presses from the user.

The difference between this and the useMention is that useMention creates editable mentions that can be changed over an over again. This creates atom mention which are inserted into the editor as non editable nodes. Backspacing into this node will delete the whole mention.

In order to properly support keybindings you will need to provide a list of data that is to be shown to the user. This allows for the user to press the arrow up and arrow down key.

You can also add other supported attributes which will be added to the mention node, like href and whatever you decide upon.

Signature:

export declare function useMentionAtom<Data extends MentionAtomNodeAttributes = MentionAtomNodeAttributes>(props: UseMentionAtomProps<Data>): UseMentionAtomReturn<Data>;

Parameters:

Parameter	Type	Description
props	UseMentionAtomProps<Data>	the props that can be passed through to the mention atom.

Returns:

UseMentionAtomReturn<Data>

function useMenuNavigation()

This hook provides the primitives for rendering a dropdown menu within

Signature:

export declare function useMenuNavigation<Item = any>(props: MenuNavigationProps): UseMenuNavigationReturn<Item>;

Parameters:

Parameter	Type	Description
props	MenuNavigationProps

Returns:

UseMenuNavigationReturn<Item>

function useMultiPositioner()

A positioner for your editor. This returns an array of active positions and is useful for tracking the positions of multiple items in the editor.

import { Positioner } from 'remirror/extensions';
import { useMultiPositioner } from '@remirror/react';

const positioner = Positioner.create({
  ...config, // custom config
})

const MenuComponent: FC = () => {
  const positions = usePositioner(positioner, []);

  return (
    <>
      {
        positions.map(({ ref, bottom, left, key }) => (
          <div style={{ bottom, left }} ref={ref} key={key}>
            <MenuIcon {...options} />
          </div>
        )
      }
    </>
  )
};

Signature:

export declare function useMultiPositioner<Data = any>(positioner: PositionerParam, deps: unknown[]): Array<UseMultiPositionerReturn<Data>>;

Parameters:

Parameter	Type	Description
positioner	PositionerParam	the positioner which will be used
deps	unknown[]	an array of dependencies which will cause the hook to rerender with an updated positioner. This is the only way to update the positioner.

Returns:

Array<UseMultiPositionerReturn<Data>>

function usePositioner()

A hook for creating a positioner with the PositionerExtension. When an active position exists for the provided positioner it will return an object with the ref, top, left, bottom, right properties.

Signature:

export declare function usePositioner<Data = any>(positioner: StringPositioner, isActive?: boolean): UsePositionerReturn<Data>;

Parameters:

Parameter	Type	Description
positioner	StringPositioner	the positioner to use which can be a string or a Positioner instance.
isActive	boolean	(Optional) Set this to a boolean to override whether the positioner is active. true leaves the behaviour unchanged. In a recent update, the positioner is now automatically memoized for you.

Returns:

UsePositionerReturn<Data>

Remarks:

Must apply the ref to the component when called.

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

const MenuComponent: FC = () => {
  const positions = usePositioner('bubble');

  return (
    <div style={{ bottom, left }} ref={ref}>
      <MenuIcon {...options} />
    </div>
  );
}

const Wrapper = () => (
  <Remirror extensions={[]}>
    <MenuComponent />
  </Remirror>
)

function usePositioner()

Signature:

export declare function usePositioner<Data = any>(positioner: Positioner | CallbackPositioner, deps: unknown[]): UsePositionerReturn<Data>;

Parameters:

Parameter	Type	Description
positioner	Positioner | CallbackPositioner
deps	unknown[]

Returns:

UsePositionerReturn<Data>

function useSuggest()

This hook allows you to dynamically create a suggester which can respond to user input of activation characters or regex patterns.

By adding a suggester it is possible to keep track of what the user has typed and receive meaningful information in return.

This includes

• The range of the matching text - The matching text value - The query value, which excludes the matching character (or character regex). - The matching capture groups [FULL_MATCH, MATCHING_CHARACTER, CUSTOM_GROUPS]

The return value has two keys, exit and change which can both be undefined. The reason for including both the exit and change return values is that it's possible for both to occur at the the same time during a **jump** from one [[Suggester]] _match_ to another suggester match.

The cursor has exited and entered (changed) at the same time.

Signature:

export declare function useSuggest(props: UseSuggesterProps): UseSuggestReturn;

Parameters:

Parameter	Type	Description
props	UseSuggesterProps

Returns:

UseSuggestReturn

variable useSuggester

Warning: This API is now obsolete.

• use useSuggest

Signature:

useSuggester: typeof useSuggest

interface EmojiState

Signature:

export interface EmojiState extends Pick<EmojiSuggestHandlerProps, 'range' | 'query' | 'exit'> 

Extends: Pick<EmojiSuggestHandlerProps, 'range' | 'query' | 'exit'>

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

property apply

The command to run to replace the query with the request emoji.

Signature:

apply: EmojiSuggestHandlerCommand;

property list

The list of emoji generated by the query.

Signature:

list: FlatEmojiWithUrl[];

interface FlatEmojiWithUrl

Signature:

export interface FlatEmojiWithUrl extends FlatEmoji 

Extends: FlatEmoji

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

property url

The svg url for CDN access.

Signature:

url: string;

interface MentionAtomState

Signature:

export interface MentionAtomState<Data extends MentionAtomNodeAttributes = MentionAtomNodeAttributes> extends Pick<SuggestChangeHandlerProps, 'name' | 'query' | 'text' | 'range'> 

Extends: Pick<SuggestChangeHandlerProps, 'name' | 'query' | 'text' | 'range'>

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

property command

A command that will update the current matching region with the provided attributes. To see what can be accomplished please inspect the type of the attrs which should be passed through.

Signature:

command: (attrs: Data) => void;

property reason

The reason for the change.

Signature:

reason: ChangeReason;

interface MentionState

Signature:

export interface MentionState<Data extends MentionExtensionAttributes = MentionExtensionAttributes> extends Pick<SuggestChangeHandlerProps, 'name' | 'query' | 'text' | 'range'> 

Extends: Pick<SuggestChangeHandlerProps, 'name' | 'query' | 'text' | 'range'>

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

property command

This command when the mention is active.

Signature:

command: (item: Data) => void;

property reason

The reason for the change.

Signature:

reason: ChangeReason;

interface MenuNavigationOptions

Signature:

export interface MenuNavigationOptions 

property direction

The direction of the arrow key press.

Signature:

direction?: MenuDirection;

property dismissKeys

Keys that can dismiss the menu.

Signature:

dismissKeys?: KeyBindingNames[];

property focusOnClick

When true, refocus the editor when a click is made.

Signature:

focusOnClick?: boolean;

property submitKeys

Keys that can submit the selection.

Signature:

submitKeys?: KeyBindingNames[];

interface UseEditorFocusProps

Signature:

export interface UseEditorFocusProps 

property blurOnInactive

Set this to true if you want to also update the focus value when the user focuses on other windows or tabs (outside of the current DOM).

Signature:

blurOnInactive?: boolean;

property ignoredElements

The elements that can be focused without setting isFocused to false.

Signature:

ignoredElements?: Array<Element | null>;

interface UseEmojiProps

Signature:

export interface UseEmojiProps extends MenuNavigationOptions 

Extends: MenuNavigationOptions

property direction

The direction of the arrow key press.

Signature:

direction?: MenuDirection;

property dismissKeys

Keys that can dismiss the menu.

Signature:

dismissKeys?: KeyBindingNames[];

property focusOnClick

When true, refocus the editor when a click is made.

Signature:

focusOnClick?: boolean;

property submitKeys

Keys that can submit the selection.

Signature:

submitKeys?: KeyBindingNames[];

interface UseEmojiReturn

Signature:

export interface UseEmojiReturn extends UseMenuNavigationReturn<FlatEmojiWithUrl> 

Extends: UseMenuNavigationReturn<FlatEmojiWithUrl>

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

property index

The selected index.

Signature:

index: number;

property setIndex

Signature:

setIndex: (index: number) => void;

property state

The state of the current query, only available when active.

Signature:

state: EmojiState | null;

interface UseMentionAtomProps

Signature:

export interface UseMentionAtomProps<Data extends MentionAtomNodeAttributes = MentionAtomNodeAttributes> extends MenuNavigationOptions, Pick<MentionAtomNodeAttributes, 'replacementType'> 

Extends: MenuNavigationOptions, Pick<MentionAtomNodeAttributes, 'replacementType'>

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

property direction

The direction of the arrow key press.

Signature:

direction?: MenuDirection;

property dismissKeys

Keys that can dismiss the menu.

Signature:

dismissKeys?: KeyBindingNames[];

property focusOnClick

When true, refocus the editor when a click is made.

Signature:

focusOnClick?: boolean;

property ignoreMatchesOnDismiss

Whether matches should be permanently ignored when the user dismisses the mention suggestion.

Signature:

ignoreMatchesOnDismiss?: boolean;

property items

The list of data from which an index can be calculated. Must include at least an id and a label.

Signature:

items: Data[];

property submitKeys

Keys that can submit the selection.

Signature:

submitKeys?: KeyBindingNames[];

interface UseMentionAtomReturn

Signature:

export interface UseMentionAtomReturn<Data extends MentionAtomNodeAttributes = MentionAtomNodeAttributes> extends UseMenuNavigationReturn<Data> 

Extends: UseMenuNavigationReturn<Data>

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

property index

The selected index.

Signature:

index: number;

property setIndex

Signature:

setIndex: (index: number) => void;

property state

Signature:

state: MentionAtomState<Data> | null;

interface UseMentionProps

Signature:

export interface UseMentionProps<Data extends MentionExtensionAttributes = MentionExtensionAttributes> extends MenuNavigationOptions 

Extends: MenuNavigationOptions

property direction

The direction of the arrow key press.

Signature:

direction?: MenuDirection;

property dismissKeys

Keys that can dismiss the menu.

Signature:

dismissKeys?: KeyBindingNames[];

property focusOnClick

When true, refocus the editor when a click is made.

Signature:

focusOnClick?: boolean;

property ignoreMatchesOnDismiss

Whether matches should be permanently ignored when the user presses escape.

Signature:

ignoreMatchesOnDismiss?: boolean;

property items

The list of data from which an index can be calculated. Must include at least an id and a label.

Signature:

items: Data[];

property onExit

This method is called when a user induced exit happens before a mention has been created. It receives the state, and gives the consumer of this hook the opportunity to manually create their own mention

Leave this undefined to ignore exits.

To enable automatic exit handling. The following will automatically set the id to be the query and the label to be the full matching text. Extra attrs like href can be added by you to the attrs object parameter.

const mentionState = useMention({ items, onExit(_, command) => command(), });

Signature:

onExit?: UseMentionExitHandler<Data>;

property submitKeys

Keys that can submit the selection.

Signature:

submitKeys?: KeyBindingNames[];

interface UseMentionReturn

Signature:

export interface UseMentionReturn<Data extends MentionExtensionAttributes = MentionExtensionAttributes> extends UseMenuNavigationReturn<Data> 

Extends: UseMenuNavigationReturn<Data>

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

property index

The selected index.

Signature:

index: number;

property setIndex

Signature:

setIndex: (index: number) => void;

property state

Signature:

state: MentionState<Data> | null;

interface UseMenuNavigationReturn

Signature:

export interface UseMenuNavigationReturn<Item = any> extends Pick<MultishiftPropGetters<Item>, 'getMenuProps' | 'getItemProps'>, Pick<MultishiftHelpers<Item>, 'itemIsSelected' | 'indexIsSelected' | 'indexIsHovered' | 'itemIsHovered'>, Pick<MultishiftState<Item>, 'hoveredIndex'> 

Extends: Pick<MultishiftPropGetters<Item>, 'getMenuProps' | 'getItemProps'>, Pick<MultishiftHelpers<Item>, 'itemIsSelected' | 'indexIsSelected' | 'indexIsHovered' | 'itemIsHovered'>, Pick<MultishiftState<Item>, 'hoveredIndex'>

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

property index

The selected index.

Signature:

index: number;

property setIndex

Signature:

setIndex: (index: number) => void;

interface UseMultiPositionerReturn

Signature:

export interface UseMultiPositionerReturn<Data = any> extends PositionerPosition 

Extends: PositionerPosition

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

property data

Metadata associated with the position

Signature:

data: Data;

property element

The element that the ref has found.

Signature:

element?: HTMLElement;

property key

A key to uniquely identify this positioner. This can be applied to the react element.

Signature:

key: string;

property ref

This ref must be applied to the component that is being positioned in order to correctly obtain the position data.

Signature:

ref: RefCallback<HTMLElement>;

interface UseSuggesterProps

Signature:

export interface UseSuggesterProps extends Except<Suggester, 'onChange'> 

Extends: Except<Suggester, 'onChange'>

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

property ignoreFocus

Set to true to ignore changes which are purely caused by focus events.

TODO - NOT YET IMPLEMENTED

Signature:

ignoreFocus?: boolean;

interface UseSuggestReturn

Signature:

export interface UseSuggestReturn extends SuggestStateMethods 

Extends: SuggestStateMethods

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

property change

Signature:

change: (Pick<SuggestChangeHandlerProps, 'text' | 'query' | 'range' | 'match'> & ChangeReasonProps) | undefined;

property exit

Signature:

exit: (Pick<SuggestChangeHandlerProps, 'text' | 'query' | 'range' | 'match'> & ExitReasonProps) | undefined;

type MentionAtomNodeAttributes

The attrs that will be added to the node. ID and label are plucked and used while attributes like href and role can be assigned as desired.

Signature:

export type MentionAtomNodeAttributes = ProsemirrorAttributes<OptionalMentionAtomExtensionProps & {
    id: string;
    label: string;
}>;

References: ProsemirrorAttributes

type MenuDirection

Signature:

export type MenuDirection = 'horizontal' | 'vertical';

type UseMentionExitHandler

Signature:

export type UseMentionExitHandler<Data extends MentionExtensionAttributes = MentionExtensionAttributes> = (props: OnExitProps<Data>, command: (attrs?: Partial<Data>) => void) => void;

type UsePositionerReturn

Signature:

export type UsePositionerReturn<Data = any> = UsePositionerReturnActive<Data> | UsePositionerReturnInactive<Data>;