State flags

Sigma maintains state for every node, every edge, and the graph as a whole. State flags drive conditional styles and can be read or updated at any time.

Node state

interface BaseNodeState {
  isHovered: boolean; // Mouse is over this node (or its label when nodeLabelEvents is "extend")
  isLabelHovered: boolean; // Mouse is over this node's label (only set when nodeLabelEvents is "separate")
  isHidden: boolean; // Node is hidden from rendering
  isHighlighted: boolean; // Node is highlighted (e.g., search result)
  isDragged: boolean; // Node is being dragged
}

Default: all false.

Edge state

interface BaseEdgeState {
  isHovered: boolean; // Mouse is over this edge (requires enableEdgeEvents, or edgeLabelEvents: "extend" for label-driven hover)
  isLabelHovered: boolean; // Mouse is over this edge's label (only set when edgeLabelEvents is "separate")
  isHidden: boolean; // Edge is hidden from rendering
  isHighlighted: boolean; // Edge is highlighted
}

Default: all false.

Graph state

interface BaseGraphState {
  isIdle: boolean; // No user interaction in progress
  isPanning: boolean; // User is panning
  isZooming: boolean; // User is zooming
  isDragging: boolean; // User is dragging a node
  hasHovered: boolean; // At least one node or edge is hovered
  hasHighlighted: boolean; // At least one node is highlighted
}

Default: isIdle: true, all others false.

Reading and writing state

// Nodes
renderer.getNodeState("node-1");
renderer.setNodeState("node-1", { isHighlighted: true }); // partial merge
renderer.setNodesState(["n1", "n2"], { isHidden: true }); // batch

// Edges
renderer.getEdgeState("edge-1");
renderer.setEdgeState("edge-1", { isHighlighted: true });
renderer.setEdgesState(["e1", "e2"], { isHidden: true });

// Graph
renderer.getGraphState();
renderer.setGraphState({ hasActiveSubgraph: true });

State updates automatically schedule a render. Call refresh({ skipIndexation: true }) if you need the update to take effect immediately.

Custom state via TypeScript generics

Extend the base interfaces to add your own state flags:

const renderer = new Sigma(graph, container, {
  customNodeState: {
    isActive: false,
  },
  customGraphState: {
    hasActiveSubgraph: false,
  },
  styles: {
    nodes: [
      { color: { attribute: "color" } },
      {
        when: (_attrs, state, graphState) => graphState.hasActiveSubgraph && !state.isActive,
        then: { color: "#f6f6f6" },
      },
    ],
  },
});

// TypeScript now knows about your custom flags:
renderer.setNodeState("node-1", { isActive: true });
renderer.setGraphState({ hasActiveSubgraph: true });

Custom state flags can be used in style predicates just like built-in ones.