Usage guidesElements

Element states

Style selection and highlighting, update states, and restore selection after data changes

View source on GitHub

States record whether an element is selected, highlighted, or marked by your application. One element can have several states, such as selected and awaiting review.

States, Behaviors, and styles

  • A state records a current flag, such as selected.
  • A Behavior decides when to change it, such as click-select responding to clicks.
  • A state style decides its appearance, such as a purple selected outline.

Listening to node:click does not select nodes; defining stateStyles does not create an interaction. Behaviors and application code can both change states.

Built-in states

StateMeaningUse case
defaultBase appearanceDisplay an element with its base styles
selectedSelectionMark nodes, edges, or Combos the user has selected
activeActivationEmphasize the element currently being interacted with
highlightHighlightingEmphasize search results or related paths
inactiveDe-emphasisDim elements outside the current focus
disabledDisabled appearanceShow an unavailable element and enforce interaction limits in application code
hiddenVisibilityHide an element temporarily

Clear the states to restore base styling. To show elements hidden by a collapsed Combo, expand the Combo. See the side-by-side state examples.

Configure state styles

Basic configuration

Use node.stateStyles for nodes, edge.stateStyles for edges, and combo.style.stateStyles for Combos. In the new Graph() options, set the fields each named state overrides. Other fields keep their base values or values from other applied states.

const stateOptions = {
  node: { stateStyles: { selected: { stroke: '#6d28d9', strokeWidth: 3 } } },
  edge: { stateStyles: { highlight: { stroke: '#008765', lineWidth: 3 } } },
  combo: { style: { stateStyles: { selected: { stroke: '#6d28d9', strokeWidth: 2 } } } },
};

Custom states

Set fill in node.stateStyles.review to mark nodes awaiting review in orange. A starts selected. Click Toggle review to add an orange fill while keeping its purple outline. Replace with highlight switches A to green highlighting. Clear A removes its states.

Loading example…
A starts selected. Toggle review adds orange; Replace keeps only highlight; Clear removes A’s states. B remains the base-style comparison
const toggle = (state: ElementState) => {
  const enabled = graph.getItemStates('A').includes(state);
  graph.setItemState('A', state, !enabled);
};
const replace = () => graph.setElementStates('A', ['highlight']);
const clear = () => graph.clearItemStates('A');

Nodes and edges can use custom state names for styling. Combo style overrides use the supported built-in states. See Combo state styles.

Set element states

Set initial states in data

Declare initial states in the states array on a node, edge, or Combo. In this example, A and Storage start selected, and the A–B edge starts highlighted.

const data = {
  nodes: [
    { id: 'A', x: 0, y: 0, states: ['selected'] },
    { id: 'B', x: 160, y: 0, comboId: 'storage' },
  ],
  edges: [{ id: 'A-B', source: 'A', target: 'B', states: ['highlight'] }],
  combos: [{ id: 'storage', states: ['selected'] }],
};

Update states at runtime

After the initial await graph.render(), use setItemState() to add one state and preserve the others. Use setElementStates() to replace the complete state set for each supplied element.

graph.setItemState('A', 'review', true);
graph.setElementStates('A', ['selected', 'review']);
graph.setElementStates({ A: ['selected'], 'A-B': ['highlight'], storage: ['selected'] });

Add or remove states in a batch

Use batchSetState() to update specific states on several elements in one operation. The remaining states stay in place.

graph.batchSetState([
  { id: 'A', state: 'review', value: true },
  { id: 'A-B', state: 'highlight', value: true },
  { id: 'storage', state: 'selected', value: true },
]);

Combine state styles

Nodes and edges apply styles in state order. When multiple states define the same field, the later one wins. For example, ['selected', 'review'] can apply a selection outline and a review fill together. Combos use the fixed order active → highlight → selected → disabled → inactive. See the node, edge, and Combo options.

Combine click selection and hover highlighting

The next example uses click-select for selection and hover-highlight to emphasize related elements. Click selection uses a purple outline, and hover highlighting uses green. Use a custom state such as review for a persistent business flag. See selection synchronization to connect application panels.

Preserve selection when replacing data

Click A, then Shift-click B and the horizontal A–C edge. Choose Keep selected. A and A–C stay selected, B is removed with the old data, and the new node D uses its base style. Reset the example, select elements again, and choose Reload data to compare a direct replacement.

Loading example…
Click or Shift-click to select; hover to highlight. Reload clears selection; Keep selected preserves only selected IDs still present. Reset restores A/B/C
const reload = async (keepSelected: boolean) => {
  const nodes = new Set(keepSelected ? graph.findNodesByState('selected') : []);
  const edges = new Set(keepSelected ? graph.findEdgesByState('selected') : []);
  const next = nextData();
  await graph.setData({
    ...next,
    nodes: next.nodes.map((node) => ({
      ...node, states: nodes.has(node.id) ? ['selected'] : [],
    })),
    edges: next.edges.map((edge) => ({
      ...edge, states: edge.id && edges.has(edge.id) ? ['selected'] : [],
    })),
  }, { fitView: false });
};

Before calling setData(), query the selected node and edge IDs separately, then write matching selections to states in the incoming data. Edges need explicit stable IDs. The example restores only selected and uses fitView: false to keep the camera view.

Clear element states

Clear all states

Use clearItemStates() to clear one element. To clear several elements at once, supply an empty array for each.

graph.clearItemStates('A');
graph.setElementStates({ A: [], 'A-B': [], storage: [] });

Clear a specific state

Pass false as the third argument to setItemState() to remove a single state. This example removes review and keeps A's selection.

graph.setItemState('A', 'review', false);

Clear the same state from multiple elements

Find the highlighted edges, then use batchSetState() to clear their highlights.

graph.batchSetState(
  graph.findEdgesByState('highlight').map((id) => ({ id, state: 'highlight', value: false })),
);

Query element states

Read and check an element's states

getItemStates() returns the states of a node, edge, or Combo as an array. The array is empty when the element has no states. Use includes() to check for a particular state.

const states = graph.getItemStates('A');
const isSelected = states.includes('selected');

Find elements with a specific state

Query nodes, edges, or Combos by state. Each method returns matching element IDs.

const selectedNodeIds = graph.findNodesByState('selected');
const highlightedEdgeIds = graph.findEdgesByState('highlight');
const selectedComboIds = graph.findCombosByState('selected');

Common questions

Why did adding a state not change appearance?

Check that supported style fields are configured. The node whole-object style function currently skips stateStyles; use per-field configuration for state appearance. See style functions.

Why did setting selected emit no selection event?

Programmatic state changes do not synthesize node:selectchange; click-select emits it. Synchronize business UI explicitly after programmatic writes. See selection synchronization.

Why is an element still hidden after clearing states?

Check whether it belongs to a collapsed Combo. Expand that structure, then check the business hidden flag.

Why did clearing highlighting also remove selection?

Check for clearItemStates or full replacement without selected. Remove only the state your code owns to preserve others.

Why were some selected elements not restored?

Check whether the new dataset still contains their IDs and whether edge IDs are stable. The example deliberately drops removed elements and preserves only selected.

Do state updates need another render?

No. State methods schedule drawing after initialization; update application UI through queries or your own synchronization logic.

Continue with state and visibility methods, node styles, edge styles, and interaction combinations.

Related runnable examples

Element overview

Explore G6Lite element types, visual parts, states, and custom rendering examples

Node overview

Learn about built-in and custom nodes, node data, styling, and states in G6Lite

On this page

States, Behaviors, and stylesBuilt-in statesConfigure state stylesBasic configurationCustom statesSet element statesSet initial states in dataUpdate states at runtimeAdd or remove states in a batchCombine state stylesCombine click selection and hover highlightingPreserve selection when replacing dataClear element statesClear all statesClear a specific stateClear the same state from multiple elementsQuery element statesRead and check an element's statesFind elements with a specific stateCommon questionsWhy did adding a state not change appearance?Why did setting selected emit no selection event?Why is an element still hidden after clearing states?Why did clearing highlighting also remove selection?Why were some selected elements not restored?Do state updates need another render?