This page documents the global configuration system for customizing handler appearance and behavior. Handlers are components that provide interactive controls for manipulating cells (vertices and edges) in the graph. The configuration system allows you to customize visual appearance (colors, sizes, stroke widths) and behavioral settings (rotation, virtual bends, cursors) without modifying handler classes.
For information about handler architecture and lifecycle, see Handler System Overview. For information about specific handlers like VertexHandler and EdgeHandler, see VertexHandler and EdgeHandler.
The handler configuration system consists of three global configuration objects that control different aspects of handler behavior:
Sources: packages/core/src/view/handler/config.ts1-278 packages/core/src/util/Constants.ts1-422
HandleConfig defines shared properties for handles used by both VertexHandler and EdgeHandler. Handles are the interactive control points (squares, circles) that appear when a cell is selected.
| Property | Type | Default | Description |
|---|---|---|---|
fillColor | string | HANDLE_FILLCOLOR (#00FF00) | Fill color for standard handles |
strokeColor | string | HANDLE_STROKECOLOR (black) | Stroke color for handles |
size | number | HANDLE_SIZE (6) | Size in pixels for standard handles |
labelFillColor | string | LABEL_HANDLE_FILLCOLOR (yellow) | Fill color for label handles |
labelSize | number | LABEL_HANDLE_SIZE (4) | Size in pixels for label handles |
labelCursor | string | 'default' | Cursor style for label handles |
Handles are created by handlers when cells are selected. The configuration affects:
VertexHandleFor a concrete example of HandleConfig properties being modified at runtime, see packages/html/stories/CustomHandlesConfiguration.stories.ts82-86
Sources: packages/core/src/view/handler/config.ts169-223 packages/core/src/util/Constants.ts213-235 packages/html/stories/CustomHandlesConfiguration.stories.ts82-86
EdgeHandlerConfig controls the appearance and behavior of EdgeHandler and its subclasses (ElbowEdgeHandler, EdgeSegmentHandler). This configuration affects edge selection borders, handle shapes, and interactive features like virtual bends.
| Property | Type | Default | Description |
|---|---|---|---|
selectionColor | string | EDGE_SELECTION_COLOR (#00FF00) | Color of the edge selection border |
selectionStrokeWidth | number | EDGE_SELECTION_STROKEWIDTH (1) | Width of the selection border |
selectionDashed | boolean | EDGE_SELECTION_DASHED (true) | Whether selection border is dashed |
handleShape | 'circle' | 'square' | 'square' | Shape of edge bend handles |
connectFillColor | string | CONNECT_HANDLE_FILLCOLOR (#0000FF) | Fill color for connection handles |
virtualBendsEnabled | boolean | false | Enable virtual bend points on segments |
virtualBendOpacity | number | 20 | Opacity (0-100) of virtual bends |
addBendOnShiftClickEnabled | boolean | false | Enable adding bends with Shift+Click |
removeBendOnShiftClickEnabled | boolean | false | Enable removing bends with Shift+Click |
cursorBend | string | 'crosshair' | Cursor for bend handles |
cursorMovable | string | 'move' | Cursor for movable edges |
cursorTerminal | string | 'pointer' | Cursor for terminal handles |
cursorVirtualBend | string | 'crosshair' | Cursor for virtual bends |
For a concrete example of EdgeHandlerConfig properties being modified at runtime, see packages/html/stories/CustomHandlesConfiguration.stories.ts72-80
Sources: packages/core/src/view/handler/config.ts40-166 packages/core/src/view/handler/EdgeHandler.ts400-408 packages/html/stories/CustomHandlesConfiguration.stories.ts72-80
Virtual bends are semi-transparent handles that appear at the midpoint of each edge segment when virtualBendsEnabled is true. They allow users to add new waypoints without using keyboard modifiers.
Implementation Details:
setOpacity() from packages/core/src/view/handler/EdgeHandler.ts826isVirtualBendsEnabled() at packages/core/src/view/handler/EdgeHandler.ts400-408Sources: packages/core/src/view/handler/EdgeHandler.ts400-408 packages/core/src/view/handler/EdgeHandler.ts575-591
VertexHandlerConfig controls the appearance and behavior of VertexHandler, which provides interactive controls for resizing and rotating vertices.
| Property | Type | Default | Description |
|---|---|---|---|
selectionColor | string | VERTEX_SELECTION_COLOR (#00FF00) | Color of the vertex selection border |
selectionStrokeWidth | number | VERTEX_SELECTION_STROKEWIDTH (1) | Width of the selection border |
selectionDashed | boolean | VERTEX_SELECTION_DASHED (true) | Whether selection border is dashed |
rotationEnabled | boolean | false | Enable rotation handle for vertices |
cursorMovable | string | 'move' | Cursor for movable vertices |
The configuration primarily affects the selection border and rotation feature:
For a concrete example of VertexHandlerConfig properties being modified at runtime, see packages/html/stories/CustomHandlesConfiguration.stories.ts88-93
Sources: packages/core/src/view/handler/config.ts226-277 packages/core/src/view/handler/VertexHandler.ts109-111 packages/core/src/view/handler/VertexHandler.ts305-313
The rotation handle is a special circular handle that appears above selected vertices when rotationEnabled is true. It allows users to rotate the vertex by dragging.
Implementation Details:
Sources: packages/core/src/view/handler/VertexHandler.ts109-111 packages/core/src/view/handler/VertexHandler.ts305-313
Each configuration object has an associated reset function that restores all properties to their default values. These functions are useful for:
| Function | Configuration Object | Source |
|---|---|---|
resetHandleConfig() | HandleConfig | packages/core/src/view/handler/config.ts221-223 |
resetEdgeHandlerConfig() | EdgeHandlerConfig | packages/core/src/view/handler/config.ts164-166 |
resetVertexHandlerConfig() | VertexHandlerConfig | packages/core/src/view/handler/config.ts275-277 |
All reset functions use the shallowCopy utility from packages/core/src/internal/clone-utils.ts to restore original values. Each config module captures a snapshot of defaults at module load time:
Reset mechanism diagram
Sources: packages/core/src/view/handler/config.ts156-166 packages/core/src/view/handler/config.ts213-223 packages/core/src/view/handler/config.ts267-277
Storybook uses reset functions in a preview decorator to ensure each story starts with a clean configuration state. The decorator runs resetEdgeHandlerConfig(), resetHandleConfig(), and resetVertexHandlerConfig() before each story executes, then the story re-applies only its own custom settings.
Storybook reset lifecycle
Sources: packages/html/stories/CustomHandlesConfiguration.stories.ts58-170 packages/core/src/view/handler/config.ts156-277
Handler classes access configuration properties at runtime, allowing dynamic behavior changes without recreating handlers.
EdgeHandler queries EdgeHandlerConfig at multiple points:
Key Access Points:
Sources: packages/core/src/view/handler/EdgeHandler.ts474-492 packages/core/src/view/handler/EdgeHandler.ts644-651
VertexHandler queries VertexHandlerConfig for selection appearance and rotation:
Key Access Points:
Sources: packages/core/src/view/handler/VertexHandler.ts445-463 packages/core/src/view/handler/VertexHandler.ts109-111
HandleConfig is accessed by multiple components for creating handles:
Usage by VertexHandler:
Usage by EdgeHandler:
Usage by VertexHandle:
Sources: packages/core/src/view/handler/VertexHandler.ts469-504 packages/core/src/view/handler/EdgeHandler.ts626-674 packages/core/src/view/cell/VertexHandle.ts194-198
Set config object properties before constructing any Graph instance. Because the config objects are module-level singletons, all subsequently created handlers will use the new values. See packages/html/stories/CustomHandlesConfiguration.stories.ts68-93 for a complete example.
Modify a config property, perform an operation, then call the matching reset function (resetEdgeHandlerConfig(), resetHandleConfig(), or resetVertexHandlerConfig()) in a finally block to restore defaults.
In test setup (beforeEach), call all three reset functions to guarantee each test case starts from the documented defaults. This prevents configuration leakage between tests.
Each story relies on the preview decorator having already called the reset functions. The story then sets only the properties it needs. See packages/html/stories/CustomHandlesConfiguration.stories.ts58-170 for the reference implementation.
Handler configuration is part of maxGraph's broader configuration system. Related configuration objects include:
Sources: packages/website/docs/usage/global-configuration.md1-92 packages/core/src/util/config.ts1-201 packages/core/src/view/style/config.ts1-159
Refresh this wiki