Navigation Feedback

Core Plugin

NavigationFeedbackPlugin is part of Plate core and is included by createPlateEditor automatically. You don't need to add it to the plugins array for the defaults to work.

Configure Duration

The default flash lasts 1.6 seconds. If you want it tighter or longer, use the top-level navigationFeedback editor option:

import { createPlateEditor } from 'platejs/react';
 
const editor = createPlateEditor({
  navigationFeedback: {
    duration: 1200,
  },
});Copy

• navigationFeedback.duration: Default flash duration in milliseconds. Default: 1600.

Disable the plugin entirely if you don't want any landed-target flash:

const editor = createPlateEditor({
  navigationFeedback: false,
});Copy

Flash a Target

When another action already handled scroll, focus, and selection, and you only want the visual confirmation, call editor.tf.navigation.flashTarget:

editor.tf.navigation.flashTarget({
  target: {
    path: [12],
    type: 'node',
  },
});Copy

The call returns false when the path doesn't resolve to a node, so you can branch on stale targets without throwing.

Override the duration or variant per call when this jump deserves its own look:

editor.tf.navigation.flashTarget({
  duration: 1500,
  target: {
    path: [12],
    type: 'node',
  },
  variant: 'mention',
});Copy

The variant string is written straight to data-nav-highlight, so you can key distinct CSS animations off it — 'navigated', 'mention', 'found', whatever you need.

Navigate and Flash

Most navigation actions should do four things at once: move the selection, focus the editor, scroll the target into view, and flash the landed node. editor.tf.navigation.navigate does all four, and each step is independent — skip any of them with the flags below.

Here's how the footnote plugin jumps from a reference to its definition:

editor.tf.navigation.navigate({
  focus: true,
  scroll: true,
  scrollTarget: point,
  select: {
    anchor: { offset: 0, path: firstTextPath },
    focus: { offset: 0, path: firstTextPath },
  },
  target: {
    path: definition[1],
    type: 'node',
  },
});Copy

Skip the flash when the jump should be silent:

editor.tf.navigation.navigate({
  flash: false,
  select: point,
  target: { path: [12], type: 'node' },
});Copy

Or tune the flash per call:

editor.tf.navigation.navigate({
  flash: { duration: 1200, variant: 'mention' },
  select: point,
  target: { path: [12], type: 'node' },
});Copy

If you don't pass scrollTarget, Plate picks a scroll point in this order: select.focus, select.anchor, select (when it's a Point), then editor.api.start(target.path).

Style the Landed Target

Whenever a target is active, the plugin injects transient attributes onto that node's DOM and a CSS variable with the current duration:

Style them anywhere your editor styles live:

.slate-editor [data-nav-highlight] {
  border-radius: 0.375rem;
}
 
.slate-editor [data-nav-highlight][data-nav-cycle='0'] {
  animation: plate-nav-highlight-a var(--plate-nav-feedback-duration, 900ms)
    ease-out;
}
 
.slate-editor [data-nav-highlight][data-nav-cycle='1'] {
  animation: plate-nav-highlight-b var(--plate-nav-feedback-duration, 900ms)
    ease-out;
}Copy

Highlight Custom Renders

Attribute injection fires through the plugin's nodeProps inject, so any standard PlateElement render that spreads its attributes onto the root DOM node picks up data-nav-* for free.

For atoms, inline voids, or components that need the highlight state inside JSX (e.g. on a nested button), read it with useNavigationHighlight:

import { useNavigationHighlight, usePath } from 'platejs/react';
 
export function FootnoteReferenceElement(props) {
  const path = usePath();
  const highlight = useNavigationHighlight(path);
 
  return (
    <PlateElement
      {...props}
      attributes={{
        ...props.attributes,
        'data-nav-cycle': highlight ? String(highlight.cycle) : undefined,
        'data-nav-highlight': highlight?.variant,
        'data-nav-pulse': highlight ? String(highlight.pulse) : undefined,
        'data-nav-target': highlight ? 'true' : undefined,
        style: {
          ...props.attributes.style,
          '--plate-nav-feedback-duration': highlight
            ? `${highlight.duration}ms`
            : undefined,
        },
      }}
    >
      {props.children}
    </PlateElement>
  );
}Copy

The hook returns null when this node isn't the active target and the full target ({ cycle, duration, path, pulse, type, variant }) when it is. Pass a Path, a TElement, or a TText — paths go through, nodes get resolved via editor.api.findPath.

Done. You now have a deterministic flash on every jump and the wiring to style or extend it.