useEditor()

Hook

A Hook that provides methods and state information associated with the entire editor.

const { connectors, actions, query, ...collected } = useEditor(collector);

Reference#

Parameters#

collector(state: EditorState, query: Query) => Collected
A function that collects relevant state information from the editor state. The component will re-render when the values returned by this function changes.

Returns#

Object
- connectorsObject
  - select(dom: HTMLElement, nodeId: NodeId) => HTMLElement
    Specifies the DOM that when clicked will in turn click the specified Node's user component
  - hover(dom: HTMLElement, nodeId: NodeId) => HTMLElement
    Specifies the DOM that when hovered will in turn hover the specified Node's user component
  - drag(dom: HTMLElement, nodeId: NodeId) => HTMLElement
    Specifies the DOM that when dragged will move the specified Node's user component. Only applicable if the component is rendered as an immediate child of a <Canvas /> component.
  - create(dom: HTMLElement, userElement: React.ReactElement) => HTMLElement
    Specifies the DOM that when dragged will create a new instance of the specified User Element at the drop location.
- actionsActionMethods
  - add(nodes: Node, parentId?: NodeId, index?: number) => void
    Add a Node to the given parent node ID at the specified index. By default the parentId is the id of the Root Node
  - addNodeTree(tree: NodeTree, parentId?: NodeId) => void
    Add a NodeTree to the given parent node ID at the specified index. By default the parentId is the id of the Root Node
  - clearEvents() => void
    Resets the editors events state
  - delete(nodeID: NodeId) => void
    Delete the specified Node
  - deserialize(data: SerializedNodes | string) => void
    Recreate Nodes from a SerializedNodes object/json. This will clear all the current Nodes in the editor state with the recreated Nodes
  - move(nodeId: NodeId, targetParentId: NodeId, index: number) => void
    Move a Node to the specified parent Node at the given index.
  - setProp(nodeId: NodeId, update: (props: Object) => void) => void
    Manipulate the props of the given Node
  - setCustom(nodeId: NodeId, update: (custom: Object) => void) => void
    Manipulate the custom values of the given Node
  - setHidden(nodeId: NodeId, bool: boolean) => void
    When set to true, the User Component of the specified Node will be hidden, but not removed
  - setOptions(options: Object) => void
    Update the editor's options. The options object passed is the same as the <Editor /> props.
  - selectNode(nodeId: NodeId | null) => void
    Select the specified node. You can clear the selection by passing `null`
  - history
    - undo() => void
      Undo the last recorded action
    - redo() => void
      Redo the last undone action
    - ignore() => ActionMethods
      Run an action without recording its changes in the history
    - throttle(throttleRate: number = 500) => ActionMethods
      Run an action while throttling its changes recorded to the history. This is useful if you need to group the changes made by a certain action as a single history record
- queryQueryMethods
  - getSerializedNodes() => SerializedNodes
    Return the current Nodes into a simpler form safe for storage
  - serialize() => String
    Return getSerializedNodes() in JSON
  - getOptions() => Object
    Get the options specified in the <Editor /> component
  - getDropPlaceholder(sourceNodeId: NodeId, targetNodeId: NodeId, pos: {x: number, y: number}, nodesToDOM?: (node: Node) => HTMLElement = node => node.dom)
    Given the target Node and mouse coordinates on the screen, determine the best possible location to drop the source Node. By default, the Node's DOM property is taken into consideration.
  - node(id: NodeId) => NodeHelpers
    Returns an object containing helper methods to describe the specified Node. Click here for more information.
  - parseReactElement(element: React.ReactElement) => Object
    - toNodeTree(normalize?: (node: Node, jsx: React.ReactElement) => void) => NodeTree
      Parse a given React element into a NodeTree
  - parseSerializedNode(node: SerializedNode) => Object
    - toNode(normalize?: (node: Node) => void) => Node
      Parse a serialized Node back into it's full Node form
  - parseFreshNode(node: FreshNode) => Object
    - toNode(normalize?: (node: Node) => void) => Node
      Parse a fresh/new Node object into it's full Node form, ensuring all properties of a Node is correctly initia lised. This is useful when you need to create a new Node.
  - history
    - canUndo() => boolean
      Returns true if undo is possible
    - canRedo() => boolean
      Returns true if redo is possible
- inContextboolean
  Returns false if the component is rendered outside of the <Editor />. This is useful if you are designing a general component that you also wish to use outside of Craft.js.
- ...collectedCollected
  The collected values returned from the collector

Examples#

Collecting state information#

import {useEditor} from "@craftjs/core";

const Example = () => {
  const { hoveredNodeId } = useEditor((state) => ({
    hoveredNodeId: state.events.hovered
  }));

  return (
    <div>
      The ID of the node currently being hovered is: {hoveredNodeId}
    </div>
  )
}

Updating props#

import {useEditor} from "@craftjs/core";

const Example = () => {
  const { selectedNodeId, actions: {setProp} } = useEditor((state) => ({
    selectedNodeId: state.events.selected
  }));

  return (
    <a
      onClick={_ => {
        setProp(selectedNodeId, props => {
          props.text = "new value";
        });
      }}
    >
      Update
    </a>
  )
}

Creating new Nodes#

import {useEditor} from "@craftjs/core";

const Example = () => {
  const { query, actions } = useEditor((state, query) => ({
    hoveredNodeId: state.events.hovered
  }));

  return (
    <div>
      <a onClick={() => {
        const nodeTree = query.parseReactElement(<h2>Hi</h2>).toNodeTree();
        actions.addNodeTree(nodeTree);
      }}>
        Add a new Node from a React Element
      </a>
        
      <a onClick={() => {
        // A fresh Node is a partial Node object
        // where only the data.type property is required
        const freshNode = {
            data: {
                type: 'h1'
            }
        };
        
        // Create a new valid Node object from the fresh Node
        const node = query.parseFreshNode(freshNode).toNode();
        actions.add(node, 'ROOT');
      }}>
        Add a new Node from a Node object
      </a>
    </div>
  )
}

Hiding and Deleting a Node#

const Example = () => {
  const {selectedNodeId, actions} = useEditor((state) => ({
    selectedNodeId: state.events.selected
  }));
  return selectedNodeId && (
    <div>
      <h2>Node selected: {selectedNodeId}</h2>
      <a onClick={() => actions.hide(selectedNodeId)}>Hide</a>
      <a onClick={() => actions.delete(selectedNodeId)}>Delete</a>
    </div>
  )
}

Moving a Node#

const Example = () => {
  const [sourceId, setSourceId] = useState();
  const [targetId, setTargetId] = useState();
  
  const {selectedNodeId, actions, query} = useEditor((state) => ({
    selectedNodeId: state.events.selected
  }));

  return selectedNodeId && (
    <div>
      <h2>Node selected: {selectedNodeId}</h2>
      <div>
        <input type="text" value={sourceId} placeholder="Source" disabled />
        <button onClick={() => selectedNodeId && setSourceId(selectedNodeId)}>Set selected Node as source</button>
      </div>
      <div>
        <input type="text" value={targetId} placeholder="Target" disabled />
        <button onClick={() => selectedNodeId && setTargetId(selectedNodeId)}>Set selected Node as target</button>
      </div>
      {
        sourceId && targeId ? (
          <button onClick={() => {
            try {
              // .canDropInParent will throw an error message if the conditions failed
              query.canDropInParent(sourceId, targetId); 
              actions.move(sourceId, targetId);
            } catch (e) {
              console.error(e.message);
            } 
          }}>Move Node</button>
        )
      }
    </div>
  )
}

Getting the currently selected Node's descendants#

Query methods are also accessible from within the collector function.

import {useEditor} from "@craftjs/core";

const Example = () => {
  const { selectedDescendants } = useEditor((state, query) => ({
    selectedDescendants: state.events && query.node(state.events.selected).descendants().map(node => node.id)
  }));

  return (
    <ul>
      {
        selectedDescendants && selectedDescendants.map(id => <li>{id}</li> )
      }
    </ul>
  )
}

Displaying Drop Indicator for the best possible drop location#

const Example = () => {
  const [screenClick, setScreenClick] = useState(false);
  const [sourceId, setSourceId] = useState();
  const [targetId, setTargetId] = useState();
  
  const {selectedNodeId, actions, query} = useEditor((state) => ({
    selectedNodeId: state.events.selected
  }));

  const disableScreenClick = useEffect((e) => {
     if(e.key === "Escape") {
       setScreenClick(false);
    }
  }, [screenClick]);

  const clickOnScreen = useEffect((e) => {
    const {clientX: x, clientY: y} = e;
    const dropIndicator = query.getDropIndicator(sourceId, targetId, {x, y});
    actions.setDropIndicator(dropIndicator);
  }, [screenClick]);
  

  useEffect(() => {
    window.addEventListener("click", clickOnScreen);
    window.addEventListener("keyup", disableScreenClick);
    return (() => {
      window.removeEventListener("click", clickOnScreen);
      window.removeEventListener("keyup", disableScreenClick);
    })
  }, [clickOnScreen, disableScreenClick]);

  return selectedNodeId && (
    <div>
      <h2>Node selected: {selectedNodeId}</h2>
      <div>
        <input type="text" value={sourceId} placeholder="Source" disabled />
        <button onClick={() => selectedNodeId && setSourceId(selectedNodeId)}>Set selected Node as source</button>
      </div>
      <div>
        <input type="text" value={targetId} placeholder="Target" disabled />
        <button onClick={() => selectedNodeId && setTargetId(selectedNodeId)}>Set selected Node as target</button>
      </div>
      {
        sourceId && targeId ? (
          <button onClick={() => {
            setScreenClick(true);
          }}>
            {screenClick ? "Click anywhere on the screen to display indicator" : "Start"}
          </button>
        )
      }
    </div>
  )
}

History#

import {useEditor} from "@craftjs/core";

const Example = () => {
  const { canUndo, canRedo, actions } = useEditor((state, query) => ({
    canUndo: query.history.canUndo(),
    canRedo: query.history.canRedo()
  }));

  return (
    <div>
      {
        canUndo && <button onClick={() => actions.history.undo()}>Undo</button>
      }
      {
        canRedo && <button onClick={() => actions.history.redo()}>Redo</button>
      }

      <button onClick={() => {
        // The following action will be ignored by the history
        // Hence, it will not be possible to undo/redo the following changes
        actions.history.ignore().setProp("ROOT", props => prop.darkMode = !prop.darkMode);
      }}>
        Toggle
      </button>

      <input type="text" onChange={e => {
        // In cases where you need to perform an action in rapid successions
        // It might be a good idea to throttle the changes
        actions.history.throttle().setProp("ROOT", props => props.text = e.target.value);
      }} placeholder="Type some text" />
    </div>
  )
}

Legacy API#

For Class Components, use connectEditor instead.

Higher-Order Component

Parameters#

collector(node: Node) => Collected
A function that collects relevant state information from the corresponding Node. The component will re-render when the values returned by this function changes.

Injected Props#

...useEditor(collector)Object
Identical return values as the useEditor() hook above

Example#

import { connectEditor } from "@craftjs/core";

class SidebarInner extends React.Component {
  render() {
    const { actions, query, enabled, currentSelectedNodeId } = this.props;
    return (
      <div>
        <input type="checkbox" value={enabled} onChange={
          e => actions.setOptions(options => options.enabled = !enabled)
        } />
        <button 
          onClick={() => {
            console.log(query.serialize())
          }}
        >
            Serialize JSON to console
        </button>
      </div>
    )
  }
}

export const Sidebar = connectEditor((state) => ({
  currentSelectedNodeId: state.events.selected
}))(SidebarInner);