Style
Use declarative stylesheet values, mappers and conditions.
Style a graph with one structured sheet, not a list of selector rules.
The sheet is a plain object whose optional group blocks are nodes, edges,
parents, core and bypasses. Node and edge blocks contain property/value
pairs. A full cy.style(sheet) installs the sheet and replaces the previous
user-authored sheet. Property names accept kebab-case or camelCase; unknown
properties and invalid values throw at the call site.
cy.style({ nodes: { label: 'data(label)', 'background-color': { data: 'score', scale: 'linear', domain: [0, 1], range: ['#fee08b', '#d73027'], }, 'border-width': { case: [{ when: { selected: true }, then: 4 }], else: 1, }, }, edges: { width: { data: 'weight', scale: 'sqrt', domain: [0, 9], range: [1, 6] }, },});#Constants, mappers and conditions
Property values are constants, scale mappers or case conditionals. A mapper
reads one data field and can map it through linear, log, sqrt, pow,
symlog, diverging, ordinal, threshold or quantize scales. A domain may
be explicit or track the live data extent; missing or unmappable input uses
fallback or the property's normal default. Color output interpolates in
OKLab by default, with interpolate: 'srgb' as the explicit alternative. A
label can read a data field with the string form 'data(label)' or the special
passthrough object { data: 'label' }; both also support the first-class id
field. Labels do not accept scale or case mappers, and that data-only object
form does not make arbitrary properties data-mappable. There are no executable
style functions. The supported scale/property combinations and complete
mapper fields are listed in the style property reference.
A case mapper checks its clauses in order. A when can contain data tests,
state such as selected, or structural conditions such as parent; an array
of conditions is ANDed. The first matching then supplies the property, with
else, fallback or the channel default as the final value. Missing data
fails its comparisons. With this declarative form, values can be inspected, serialized, refreshed
and evaluated on supported GPU paths without executing application closures
per element.
Data writes refresh mapped channels for the affected elements. If an auto-domain extent changes, its mapped channel is re-derived. Selection does not run a full restyle: selected-state styling is a conditional in the default sheet. A custom definition for a property replaces that property's default selection condition as expected; include the condition explicitly when the custom color should still change on selection.
#Group behavior and compound parents
nodes and edges describe the two element groups. parents is an overlay
for compound parent nodes: it can override node properties and set compound
padding and sizing behavior. It is separate from the ordinary node block so
parent labels, child bounds and padding can be treated explicitly. core
contains viewport-level theme properties such as selection-box colors,
background interaction indicators, dim-opacity during emphasis and the
label-declutter policy. These core values are constants; they do not map per
element.
Styles support node geometry, fill/border, opacity, labels and typography,
edge lines, arrows and route families, plus common overlay/underlay and text
properties. Node shapes include standard geometric shapes, custom polygon
points, and parent-only convex-hull, round-convex-hull and concave-hull.
Hull contours follow child outer-body outlines, nested parents contribute
their contours, and concave hulls form one connected region without holes or
islands. An empty hull falls back to the parent's rectangle or rounded
rectangle. The contour is shared by drawing, borders, edge endpoints, picking,
bounds and layout dimensions. There is no public tightness or obstacle-avoidance
control.
The exact supported property/group matrix, literal defaults and accepted
values are in the style property reference. A property
familiar from CSS is not necessarily accepted on every group. Node
width, height, edge width, compound padding and font-size affect
geometry; changing them updates dependent bounds and rendered geometry as part
of style application.
Parent nodes also support miniature collapse. The parents overlay's
collapse-scale is a finite number in (0, 1] (default 0.1).
collapsed() reports the parent's own state and insideCollapsed() reports
strict descendants. collapse() and expand() scale descendants around the
parent's center while preserving the graph and hidden state. Style reads such
as width() retain authored dimensions while geometry uses the effective
scaled size. Decorations, images, charts, labels, hulls and shared
internal-edge geometry follow the descendant scale; edges crossing out of the
collapsed group keep their authored width.
Node charts are a paint-only family with kinds none, pie, stripes,
heat-strip, radial-heat and bar. chart-values has up to 255 ordered
slots; a data mapper can pass a per-node array through. Pie and stripe slots
are fractions: values below one leave transparency and values above one clamp.
Heat and bars preserve finite signed values; missing entries retain their
positions and do not shift later slots. Heat charts require chart-scale with
numeric bounds and a colour range. Bar geometry requires chart-domain and
uses a zero baseline clamped to that domain; bar colors are configured
separately. Missing heat values are transparent by default and missing bars
leave gaps. Charts do not affect bounding boxes or pick results. cy.legend()
returns mapping/chart metadata for an application-owned legend; it does not
draw one.
Nodes can also draw up to four background images, in list order with later
images composited on top. Image URLs or data URIs may be constant or mapped
per node; opacity and color/tint can also be mapped, while fit, position,
size, repeat, clipping, containment and smoothing use constant per-image lists.
The default image mode draws decoded raster content; SVG sources can be
rasterized again for zoom and export demand. Setting background-image-type
to sdf-icon instead uses an alpha silhouette tinted by
background-image-color for crisp monochrome icons. Failed URLs warn once and
draw no image. Images are paint only: they do not extend element bounds or
count as pick targets.
Rendered cores supply the decoder; a headless core may retain the style data
but cannot decode and display the image. The exact supported image property
lists and defaults are in the style-property reference.
#Bypasses and reads
bypasses is an id-keyed object of constant overrides. A bypass wins over
group definitions and defaults. It is a stylesheet declaration, not transient
element state: it may refer to an id not yet present, survives removing and
re-adding that id, and appears in cy.json(). A full sheet replacement
replaces bypasses as well. Element style() and removeStyle() are convenience
operations over those overrides; style functions are not accepted.
eles.style() reads resolved stored style for the first element (or a named
property); it does not return the declaration object. numericStyle() gives
the numeric value of a numeric property, while renderedStyle() accounts for
the rendered coordinate scale where that property has one. These synchronous
reads operate on stored channels and work headlessly. effectiveOpacity()
includes compound ancestor opacity. During a batch, style reads can remain
stale until the batch flush; see core batching.
Use these tables to choose style properties and their values. Properties are grouped by the elements they affect. Invalid names, values and group combinations throw when the sheet is compiled. The stylesheet schema describes its structure. For mapper examples and stylesheet usage, see Styling.
#Sheet shape and values
A sheet has optional props objects named nodes, edges, parents, core, and bypasses. Property names may be kebab-case or camelCase. Invalid property names, values, group combinations, and unknown sheet keys throw when the sheet is compiled. A full cy.style(sheet) replaces the user sheet, including bypasses. The stylesheet does not accept selector-rule arrays, selector strings as style rules, CSS string stylesheets, or a function for a whole group.
Colors accept CSS color names, #rgb/#rrggbb, rgb()/rgba(), hsl()/hsla(), and RGB(A) numeric arrays; they are stored as RGBA bytes. Numeric style lengths use model pixels; there is no general CSS unit conversion. Prefer finite numbers in JSON. The runtime numeric parser applies parseFloat to strings, so a numeric prefix such as "12px" is accepted even though style numbers do not have general CSS unit conversion. Unless specified otherwise, invalid enum keywords or malformed lists throw.
Mapper objects with scale or case behavior are available only for the
channels listed in Mapper support. Labels and chart-values
also accept a restricted { data: key } passthrough; it does not scale or
branch. A scale mapper looks like:
{ data: 'score', scale: 'linear', domain: [0, 100], // or 'auto' range: ['#fee08b', '#d73027'], clamp: true, fallback: '#999'}Supported scales are linear, log, sqrt, pow, symlog, diverging, ordinal, threshold, and quantize. A missing domain or domain: 'auto' tracks the live data extent. Continuous and quantize domains may use auto at either outer endpoint; diverging domains require an explicit midpoint. pow defaults to exponent 2, log to base 10, and symlog to constant 1. Ranges take numeric or color stops, or a named color scheme such as viridis, plasma, magma, inferno, ColorBrewer ramps, category10, or dark2. Colors interpolate in OKLab unless interpolate: 'srgb' is set. Missing or unmappable data uses fallback, then the channel default. Log scales use positive values only.
Conditional values use ordered case clauses. Each when is one condition or an array ANDed together; the first match wins. Conditions can compare data with eq, ne, lt, lte, gt, gte, or in, and can read state/structure such as selected, active, parent, child, collapsed, or emphasized. String and boolean data support equality and membership; numeric data supports all comparisons. Missing data never matches. The final value is else, then fallback, then the channel default.
#Groups and defaults
The defaults in the property tables are base channel defaults. The installed default sheet adds these ordinary conditional declarations:
| Group | Default sheet declarations |
|---|---|
| nodes | background-color is #999 or #0169D9 when selected; active nodes get overlay-opacity: 0.25. |
| edges | line-color and source, target, and mid-arrow colors are #999 or #0169D9 when selected; width is 3; active edges get overlay-opacity: 0.25. |
| parents | Parent overlay defaults are rectangular shape, #eee fill, 1px #ccc border, and 10px padding. Selected parents use #CCE1F9 fill and #aec8e5 border. A user's nodes block overrides parent defaults; a user's parents block overrides both. |
nodes applies to all nodes, including compound parents. edges applies to edges. parents overlays node styling for compound parents and owns the compound-sizing properties below. core affects viewport-level behavior and accepts constants only. A bypass is an id-keyed constant declaration; it beats group blocks and defaults, and can be declared before its element exists.
#Shared element channels
These channels apply to nodes and edges; parent channels use the node form.
| Property | Base default | Accepted values |
|---|---|---|
opacity |
1 |
Finite number; mapped. The parser does not restrict it to [0, 1]; use that interval for conventional opacity values. |
events |
yes |
yes/no or boolean; mapped. no/false makes the element pointer-transparent. |
visibility |
visible |
visible or hidden; mapped. hidden suppresses paint without removing the element. |
#Node and parent node properties
Unless a row says node-only or parent-only, the property is accepted in nodes and parents. A mapper can replace a constant only for properties named in the mapper inventory below. Lists and global font-face settings remain constants even where nearby values accept mappers.
#Body geometry and paint
| Property | Base default | Accepted values |
|---|---|---|
width |
30 |
Finite model-pixel number; mapped. Also edge line width. Parent size is derived from children. |
height |
30 |
Finite model-pixel number; mapped. Parent size is derived from children. |
shape |
ellipse |
Mapped keyword: ellipse, circle, rectangle, square, round-rectangle, triangle, pentagon, hexagon, heptagon, octagon, diamond, rhomboid, right-rhomboid, vee, star, tag, polygon, concave-hexagon, cut-rectangle, round-triangle, round-diamond, round-pentagon, round-hexagon, round-heptagon, round-octagon, round-tag, bottom-round-rectangle, barrel, convex-hull, round-convex-hull, or concave-hull. circle and square resolve to ellipse and rectangle. Hull shapes describe compound-parent contours. |
shape-polygon-points |
[-1,-1, 1,-1, 1,1, -1,1] |
Constant array or whitespace-separated numeric string with an even number of values and at least 3 x/y pairs in [-1, 1]. Used with shape: polygon; values after the 32nd pair are truncated. |
corner-radius |
auto |
Mapped non-negative model-pixel number or auto. auto is min(width/4, height/4, 8). |
background-color |
#999 |
Color; mapped. The default sheet supplies the selected-state color. |
background-opacity |
1 |
Number in [0, 1]; mapped; folds into fill alpha. |
background-fill |
solid |
Mapped keyword: solid, linear-gradient, radial-gradient. |
background-gradient-stop-colors |
empty | Constant color array or whitespace-separated string; at most 5 stops are drawn. |
background-gradient-stop-positions |
evenly spread | Constant array/string of percentages or numbers; clamps to [0, 100] and never decreases between stops. |
background-gradient-direction |
to-bottom |
Mapped keyword: to-bottom, to-top, to-left, to-right, to-bottom-right, to-bottom-left, to-top-right, to-top-left. |
border-color |
#000 |
Color; mapped. |
border-width |
0 |
Finite model-pixel number; mapped. |
border-opacity |
1 |
Number in [0, 1]; mapped and folded into border alpha. |
border-position |
center |
Mapped keyword: center, inside, outside. |
border-style |
solid |
Mapped keyword: solid, dashed, dotted, double. |
border-dash-pattern |
[4, 2] |
Constant numeric array, number, or whitespace-separated string. Negative entries throw. It normalizes to two on/off pairs; odd lists repeat and longer lists truncate. |
border-dash-offset |
0 |
Finite model-pixel number; mapped. |
outline-color |
#999 |
Color; mapped. |
outline-opacity |
1 |
Number in [0, 1]; mapped. |
outline-width |
0 |
Non-negative model-pixel number; mapped. |
outline-offset |
0 |
Non-negative model-pixel number; mapped. |
outline-style |
solid |
Mapped keyword: solid, dashed, dotted, double. The current double outline path renders as a solid outline. |
border-position: center places the border across the shape boundary. corner-radius only affects shapes that have rounded corners. Outlines sit outside the border and contribute to bounds; they are not pick targets.
#Labels and typography
The common text properties also apply to edges. Edge endpoint-label properties are listed separately below.
| Property | Base default | Accepted values |
|---|---|---|
label |
'' |
Constant string, data(key) string form, or { data: key } passthrough object; id reads the first-class id in either mapper form. Scale/case mappers are rejected. |
font-size |
16 |
Finite model-pixel number; mapped. |
font-family |
sans-serif |
Non-empty string, constant-only. The glyph atlas uses one font face. |
font-style |
normal |
normal, italic, or oblique; constant-only. |
font-weight |
normal |
normal, bold, bolder, lighter, or hundreds from 100 to 900; constant-only. |
color |
#000 |
Label color; mapped. |
text-opacity |
1 |
Number in [0, 1]; mapped; folds into text, outline, and text-background alpha. |
text-outline-width |
0 |
Finite model-pixel number; mapped. |
text-outline-color |
#000 |
Color; mapped. |
text-outline-opacity |
1 |
Finite number; mapped. Use [0, 1] for conventional opacity values; the parser accepts finite values outside that range. |
text-background-color |
#000 |
Color; mapped. |
text-background-opacity |
0 |
Finite number; mapped. Use [0, 1] for conventional opacity values; the parser accepts finite values outside that range. |
text-background-padding |
0 |
Finite model-pixel number; mapped. |
text-background-shape |
rectangle |
Mapped keyword: rectangle or round-rectangle. |
text-border-width |
0 |
Non-negative model-pixel number; mapped. |
text-border-color |
#000 |
Color; mapped. |
text-border-opacity |
0 |
Number in [0, 1]; mapped. |
text-border-style |
solid |
Mapped keyword: solid, dashed, dotted, double. |
text-margin-xtext-margin-y |
0 |
Finite model-pixel numbers; mapped. |
min-zoomed-font-size |
0 |
Non-negative device-pixel number; mapped. Zero disables the floor. The label hides below this zoomed, DPR-scaled size. |
text-transform |
none |
Mapped keyword: none, uppercase, lowercase. |
text-wrap |
none |
Mapped keyword: none, wrap, ellipsis. |
text-max-width |
9999 |
Non-negative model-pixel number; mapped. |
line-height |
1 |
Non-negative multiplier; mapped. |
text-overflow-wrap |
whitespace |
Mapped keyword: whitespace or anywhere. anywhere allows long words to break. |
text-justification |
auto |
Mapped keyword: auto, left, center, right. auto follows horizontal alignment. |
text-halign |
center |
Node-only mapped keyword: left, center, right. |
text-valign |
bottom |
Node-only mapped keyword: top, center, bottom. |
text-rotation |
0 (none) |
Mapped none, autorotate, or finite radians. autorotate is edge-only; nodes take numeric rotations. |
text-events |
no |
Node-only mapped yes/no or boolean. When enabled, the label box can pick the node. |
label-priority |
0 |
Node-only mapped finite number. Higher values claim space first when core.label-declutter is cull. |
Node labels align at the bottom by default. Use text-valign to change the alignment.
Wrapping preserves embedded newlines. whitespace leaves an unbreakable word overflowing; anywhere can break it. ellipsis truncates one line. A text border is drawn within the padded background box. Label dimensions join layout or fit geometry only where those operations request labels.
#Ghosts and overlays
| Property | Base default | Accepted values |
|---|---|---|
ghost |
no |
Node-only mapped yes/no or boolean; draws one extra copy of the basic node body. |
ghost-offset-xghost-offset-y |
0 |
Node-only finite model-pixel numbers; mapped. |
ghost-opacity |
0 |
Node-only number in [0, 1]; mapped. |
overlay-colorunderlay-color |
#000 |
Node and edge colors; mapped. Node layers surround the body; edge layers stroke the edge path. |
overlay-opacityunderlay-opacity |
0 |
Number in [0, 1]; mapped. The default sheet sets overlay-opacity to 0.25 on active elements. |
overlay-paddingunderlay-padding |
10 |
Non-negative model-pixel number; mapped. |
overlay-shapeunderlay-shape |
round-rectangle |
Node-only round-rectangle or ellipse; constants only. |
overlay-corner-radiusunderlay-corner-radius |
auto |
Node-only non-negative model-pixel number or auto; constants only. |
Ghosts duplicate only the basic node body, not labels or decorations. They are not pickable and do not add extents to box selection. Node overlays draw above the body but below labels. Edge underlays sit beneath edges; edge overlays sit over edges and arrows. Edge layers do not accept node-only shape/radius props.
#Background images
These properties are node-only. Image settings may be scalars or arrays; arrays distribute by image index and repeat their last item for later images. At most four image layers are composited. Only background-image, background-image-opacity, and background-image-color take mapper objects; a mapped image represents one URL per node.
| Property | Base default | Accepted values |
|---|---|---|
background-image |
none |
none, URL, url(...) wrapper, or URL array; mapped single URL is allowed. |
background-fit |
none |
Per-image none, contain, cover; scalar or non-empty array. |
background-image-opacity |
1 |
Per-image number in [0, 1]; scalar or non-empty array; mapped single value is allowed. |
background-position-xbackground-position-y |
50% |
Per-image percentage, pixel number, Npx, or N%; scalar or non-empty array. |
background-offset-xbackground-offset-y |
0 |
Per-image pixel number or percentage string; scalar or non-empty array. |
background-widthbackground-height |
auto |
Per-image auto, non-negative pixel number, Npx, or N%; scalar or non-empty array. |
background-repeat |
no-repeat |
Per-image no-repeat, repeat-x, repeat-y, or repeat; scalar or non-empty array. |
background-clip |
node |
Per-image node or none; scalar or non-empty array. |
background-image-containment |
inside |
Per-image inside or over; scalar or non-empty array. |
background-image-smoothing |
yes |
Per-image yes/no or boolean; scalar or non-empty array. |
background-image-crossorigin |
anonymous |
anonymous, use-credentials, or null; constant-only. |
background-image-type |
auto |
Per-image auto or sdf-icon; scalar or non-empty array. |
background-image-color |
#999 |
SDF icon tint; color, mapped. |
background-width-relative-to and background-height-relative-to are reserved names in the internal property vocabulary but throw as unsupported. They are not part of the accepted style surface.
#Node charts
Charts are node paint decorations; they do not change bounds or picking. The chart kind and scalar channels accept mappers. List/config values are constant-only except chart-values, which can use a { data: key } passthrough to read a per-node array.
| Property | Base default | Accepted values |
|---|---|---|
chart |
none |
Mapped none, pie, stripes, heat-strip, radial-heat, or bar. |
chart-values |
not set | Numeric/null list or whitespace-separated numeric list; { data: key } passthrough may read a per-node array. First 255 slots are kept, preserving missing slots. |
chart-colors |
category10 |
Color list or named palette; constant-only. Pie/stripe values cycle a shorter palette. |
chart-scale |
not set | Constant scale object with explicit domain and color range; only outer domain endpoints may be auto. Used by heat colors and optional bar colors. |
chart-domain |
not set | Constant two-number domain with min < max, or auto endpoint(s). Required for bars. |
chart-missing-color |
transparent |
Color; constant-only; heat missing-value appearance. |
chart-size |
1 |
Fraction in [0, 1] or percentage string; mapped. |
chart-hole |
0 |
Fraction in [0, 1] or percentage string; mapped. |
chart-start-angle |
0 radians |
Number in radians or deg/rad string; mapped. |
chart-direction |
vertical |
Mapped vertical or horizontal; stripe/bar axis. |
chart-opacity |
1 |
Number in [0, 1]; mapped. |
Pie/stripe values represent fractions: a sum below 1 leaves a transparent remainder and values over 1 clamp. Heat and bar values can be signed. Missing and non-finite entries retain their positions but do not affect extents. Heat requires an explicit scale domain and color range. Bars require chart-domain, use a zero baseline clamped to that domain, and leave missing values empty. Categorical chart-colors and chart-scale cannot both color bars.
#Edge properties
All properties here belong in edges. The common text properties above also apply to edge labels unless marked node-only. Edges have a center label and source/target endpoint labels.
#Line paint and arrows
| Property | Base default | Accepted values |
|---|---|---|
width |
3 from default sheet |
Finite model-pixel number; mapped. |
opacity |
1 |
Number; mapped. Also affects effective arrow alpha. |
line-color |
#999 |
Color; mapped; selected color is supplied by the default sheet. |
line-opacity |
1 |
Number in [0, 1]; mapped; folds into line and arrow alpha. |
line-style |
solid |
Mapped solid, dashed, or dotted. |
line-cap |
butt |
Mapped butt, round, or square. |
line-dash-pattern |
[6, 3] |
Constant numeric array/number/whitespace string; negative entries throw; normalized to two on/off pairs. |
line-dash-offset |
0 |
Finite model-pixel number; mapped. |
line-outline-width |
0 |
Non-negative model-pixel number; mapped; draws a casing under each edge line. |
line-outline-color |
#000 |
Color; mapped. |
line-fill |
solid |
Mapped solid, linear-gradient, or radial-gradient. |
line-gradient-stop-colors |
empty | Constant color list/string; at most 5 stops. |
line-gradient-stop-positions |
evenly spread | Constant percentages/numbers; clamped to [0, 100] and nondecreasing. |
arrow-scale |
1 |
Constant must be positive; mapped values are floored at 1/16. |
source-arrow-shapetarget-arrow-shape |
none |
Mapped none, triangle, arrow (triangle alias), vee, chevron, circle, square, diamond, tee, triangle-tee, circle-triangle, triangle-backcurve. |
source-arrow-colortarget-arrow-color |
#999 |
Color; mapped; selected color is supplied by the default sheet. |
source-arrow-filltarget-arrow-fill |
filled |
Mapped filled or hollow. |
source-arrow-widthtarget-arrow-widthmid-source-arrow-widthmid-target-arrow-width |
1 |
Non-negative model-pixel number, match-line, or percentage of edge width; constants only. These widths set hollow-head strokes; mid heads are currently always filled, so their width values do not change their drawing. |
mid-source-arrow-shapemid-target-arrow-shape |
none |
Same arrow keywords; mapped. |
mid-source-arrow-colormid-target-arrow-color |
#999 |
Color; mapped; selected color is supplied by the default sheet. |
Gradient stops interpolate in sRGB. Linear edge stops follow the drawn span; curved/routed edges use path length. line-opacity folds into stored line and arrow color alpha. A zero-alpha arrow reads back as shape none because stored color alpha controls whether it draws. The casing is paired with each edge in draw order. Edge overlay/underlay layers are separate from the casing.
#Edge routes and endpoints
Edges are straight by default. Set curve-style: 'bezier' for curved routes.
| Property | Base default | Accepted values |
|---|---|---|
curve-style |
straight |
Mapped straight, bezier, unbundled-bezier, segments, round-segments, taxi, round-taxi, haystack, or straight-triangle. |
control-point-step-size |
40 |
Finite model-pixel number; mapped. |
control-point-weight |
0.5 |
Finite number; mapped. |
loop-direction |
-45° |
Angle in radians or deg/rad string; mapped. |
loop-sweep |
-90° |
Angle in radians or deg/rad string; mapped. |
control-point-distances |
not set | Constant number, array, or whitespace-separated number string; mapper values are not supported. |
control-point-weights |
[0.5] |
Constant number, array, or whitespace-separated number string; mappers are not supported. |
segment-distances |
[20] |
Constant number, array, or whitespace-separated number string; mappers are not supported. |
segment-weights |
[0.5] |
Constant number, array, or whitespace-separated number string; mappers are not supported. |
segment-radii |
[15] |
Constant number, array, or whitespace-separated number string; mappers are not supported. |
radius-type |
arc-radius |
One arc-radius or influence-radius keyword, or a constant array/whitespace-separated list; mappers are not supported. |
edge-distances |
intersection |
Mapped intersection, node-position, or endpoints. |
taxi-direction |
auto |
Mapped auto, vertical, horizontal, upward, downward, leftward, rightward. |
taxi-turn |
50% |
Constant accepts a finite pixel number, percentage string, or auto; negative pixel turns select from the target side. Mappers produce pixel numbers; use fallback: auto to select auto routing, since percentage strings are constants-only. |
taxi-turn-min-distance |
10 |
Finite model-pixel number; mapped. |
taxi-radius |
15 |
Finite model-pixel number; mapped. |
taxi-track |
source |
Mapped source, target, or family. |
taxi-track-spacing |
10 |
Non-negative model-pixel number; mapped. |
haystack-radius |
0 |
Number in [0, 1]; mapped. |
source-endpointtarget-endpoint |
outside-to-node |
Constant keyword, point, or angle. Keywords: outside-to-node, inside-to-node, outside-to-line. Points have two components with optional % or px; angles are radians or deg/rad strings. |
source-distance-from-nodetarget-distance-from-node |
0 |
Non-negative model-pixel number; mapped. |
The list-valued curve properties are constants-only: a mapper's scalar output is not an array. bezier is the parallel-edge bundle family; unbundled, taxi and segment families route per edge. taxi-turn: auto participates in the taxi track pass. Endpoint outside-to-node-or-label and outside-to-line-or-label forms throw because edge-to-label bounds are not available. This catalog does not imply other endpoint forms are supported.
#Edge labels
Properties |
Base default |
Accepted values |
|---|---|---|
source-labeltarget-label |
'' |
Constant string, data(key) string form, or { data: key } passthrough object; scale/case mappers are rejected. |
source-text-offsettarget-text-offset |
0 |
Non-negative model-pixel number; mapped. |
source-text-margin-xsource-text-margin-ytarget-text-margin-xtarget-text-margin-y |
0 |
Finite model-pixel number; mapped. |
source-text-rotationtarget-text-rotation |
0 (none) |
Mapped none, autorotate, or finite radians. |
text-rotation |
0 (none) |
Shared mapped rotation; edge labels also accept autorotate. |
#Compound-parent sizing and miniatures
Compound props are constants-only and valid only in parents. Putting them in nodes, edges, or core throws. Parent base sizing defaults are 10px padding, zero minimum inner dimensions, and compound-sizing-wrt-labels: exclude.
| Property | Default | Accepted values and behavior |
|---|---|---|
padding |
10px |
Non-negative pixel number or percentage string such as 12%. Percent uses padding-relative-to. |
padding-leftpadding-rightpadding-toppadding-bottom |
unset; inherit padding |
Non-negative pixel number or percentage string; an authored side overrides uniform padding for that side. |
padding-relative-to |
width |
width, height, average, min, or max; used only with percentage padding. |
min-widthmin-height |
0 |
Non-negative model-pixel number; minimum inner dimension before padding. |
compound-sizing-wrt-labels |
exclude |
exclude or include. Include visible direct-child label bounds in model space before parent padding; a parent's own label never sizes itself. |
collapse-scale |
0.1 |
Parent-only finite number in (0, 1]; mapper or bypass is allowed. Used as the configured miniature factor when a collapsed state has no separately applied factor. |
convex-hull, round-convex-hull, and concave-hull are shape values for compound parents. Their contours follow visible direct-child outer body outlines; nested parents contribute their contours. Concave hulls remain a single connected region, may cover unrelated nodes, and have no public tightness or obstacle control. Empty hulls fall back to a rectangle, rounded for the round shapes. Child label bounds join sizing and hull inputs only with compound-sizing-wrt-labels: include. Collapse state itself is carried on node definitions and collections; collapsed: true is available as a node condition.
#Core properties
Every core value is a constant. Scale/case mapper objects are rejected.
| Property | Default | Accepted values and behavior |
|---|---|---|
selection-box-color |
#ddd |
Color for the DOM selection box. |
selection-box-opacity |
0.65 |
Number in [0, 1]. |
selection-box-border-color |
#aaa |
Color. |
selection-box-border-width |
1 |
Non-negative model-pixel number. |
active-bg-color |
#000 |
Color for the background-grab indicator. |
active-bg-opacity |
0.15 |
Number in [0, 1]. |
active-bg-size |
30 |
Non-negative model-pixel number. |
dim-opacity |
0.15 |
Number in [0, 1]; opacity outside the set passed to cy.emphasize(). |
label-declutter |
none |
none or cull; cull gives higher label-priority node labels first claim to space. |
The selection box and background-grab indicator are DOM overlays and do not appear in graph image export.
#Style transitions and animation
The sheet's transition-property, transition-duration, transition-delay
and transition-timing-function configure transitions when a style change
updates a listed channel. The transitionable set matches animate()'s
supported geometry and paint channels. Animations start immediately; there is
no queue, and an overlapping animation replaces the older one on the same
channels. Colors interpolate in OKLab.
See animations for handles, easing and sequence patterns.
See the style property reference for all supported properties, defaults and values.
#Transitions
transition-property, transition-duration, transition-delay, and transition-timing-function are per-group settings accepted in nodes, edges, and parents. They are not channels; they cannot be mapped or bypassed. transition-property is a constant list/string of properties valid for the group. Duration and delay are non-negative milliseconds, defaulting to zero. Timing defaults to linear and must name a supported easing function.
The engine currently tweens node opacity, background-color, border-color, border-width, width, height, and font-size; edge opacity, line-color, width, and font-size; and parent padding together with its node channels. Other property names can pass group validation but do not become tweenable merely by appearing in transition-property; discrete style changes snap when the style update starts. A first style application is immediate. See animations for handle and channel behavior.
#Mapper support
The following channels accept scale and conditional mappers. Every accepted property outside it takes constants only, with the restricted label/chart-values passthroughs and chart-scale configuration form noted above.
| Group | Mapper-capable properties |
|---|---|
| Nodes | background-color, border-color, width, height, border-width, opacity, shape, font-size, min-zoomed-font-size, label-priority, text-halign, text-valign, color, text-outline-width/color/opacity, text-background-color/opacity/padding, text-margin-x/y, text-rotation (except autorotate), text-transform, text-background-shape, text-wrap, text-max-width, line-height, text-overflow-wrap, text-justification, text-border-width/color/opacity/style, background-fill, background-gradient-direction, background-opacity, events, visibility, text-events, ghost and its offsets/opacity, overlay/underlay color/opacity/padding, outline color/opacity/width/offset/style, corner-radius, border-position/style/dash-offset, chart kind/opacity/size/hole/start-angle/direction, background-image/image-opacity/image-color. |
| Parents | Node channels above plus collapse-scale; parent channel values resolve only on parent slots. |
| Edges | width, opacity, font-size, color, shared text outline/background/margin/wrap/rotation/transform/border channels, text-opacity, events, visibility, overlay/underlay color/opacity/padding, line-color/style/opacity/cap/dash-offset/outline/fill, arrow-scale, source/target/mid-arrow shape and color, source/target arrow-fill, curve-style, control-point step/weight, loop direction/sweep, edge-distances, taxi direction/turn/min-distance/radius/track/track-spacing, haystack-radius, endpoint distance, and endpoint-label offset/margin/rotation. |
| Core and bypasses | None. Core properties are constants; bypass entries are constant-only. |
Mapper use on a non-mappable property, on the wrong group, or on a global font property throws. collapse-scale belongs in parents, not the nodes block. Node-only properties such as charts, images, text-events, label-priority, and shape-polygon-points are rejected in edges; route and endpoint-label properties are edge-only.
#Curved edge limits
Edge endpoints use an approximation of the node's shape rather than exact
per-shape intersection. On a 40×24 node, ellipse, circle and rectangle are
exact; round-rectangle is off by up to 2.247 model pixels at a corner, and
triangle by 8.453 at the leaf, the polygon tier's worst case. Multi-point
curves take at most 8 controls and 11 segment points. Weights clamp to
[-1, 2]. An unbundled-bezier loop uses control-point-distances[0] as its
loop distance, falling back to the step size when unset, and segment- or
taxi-styled loops render as loops.