CSS Item Styles
Aside from the mentioned styling option described in this chapter, most style implementations for nodes, edges and labels
support custom CSS classes through a cssClass
property on the style instance.
This allows to control the item visualization with CSS and enables easy CSS transitions between different states.
The CSS Item Style demo shows applications of this feature by purely relying on the cssClass
property
to style the graph items. Additionally, it showcases different highlight transitions and animations.
CSS Item Style
The cssClass
property can be used to specify one or more CSS classes on the root element of the DOM structure of the
graph item.
The following snippet shows how define a basic CSS style for nodes with the cssClass property.
<style>
.node {
fill: #17bebb;
stroke: #094c4b;
stroke-width: 4px;
}
</style>
This works for most yFiles for HTML styles, though depending on the style and the DOM elements it creates, you need to apply
different CSS rules. For example, a PolylineEdgeStyle not only has a stroke
property but usually no fill
because it is rendered with an SVG path
element.
Some styles also create more specific CSS classes for child elements of the visualization if the cssClass
property is
defined. For more information, see the dedicated documentation for the following styles:
Synchronize fill and stroke with currentColor
The Arrow implementation does not support the CSS class property. Nevertheless, it is still possible to color the arrow dependent on the CSS class of the related PolylineEdgeStyle by assigning CURRENT_COLOR or CURRENT_COLOR, which also works with Automatic Type Conversion:
<style>
.edge {
color: #e01a4f;
}
</style>
CSS Item Style Transitions
With CSS classes on item styles, it is very easy to animate state changes of graph items in yFiles for HTML.
A simple mouse-over highlight that changes the fill and stroke of the node with a ShapeNodeStyle could look like this:
<style>
.node {
fill: #17bebb;
stroke: #094c4b;
/* animate changes */
transition-property: fill, stroke, stroke-width;
transition-duration: 0.3s;
transition-timing-function: ease-in-out;
}
.node:hover {
fill: #e01a4f;
stroke: #5a0a20;
stroke-width: 4px;
}
</style>
Using the :hover
pseudo-class often works well for nodes or bigger elements in general, but keep in mind that this skips
the entire yFiles input mechanism. Particularly for edges it is usually better to let the itemHoverInputMode decide on
the hover state of the graph item because it considers the actual hit testing of the style
implementation and the current hitTestRadius.
yFiles for HTML does not guarantee to keep the graph item’s DOM element alive when changing more than just the cssClass
property during one updateVisual iteration. So to trigger CSS transitions, make sure to only change
the cssClass
property.
When adjusting a property on the style, e.g. cssClass
, also consider that the style may be shared between multiple graph
model items. Either make sure to disable style sharing, or clone the style beforehand.
Exporting Graph Items Styled by CSS
By default, the SvgExport does not consider any external stylesheets. To export graph items that are styled by external CSS rules, the cssStyleSheet property needs to be specified accordingly.
For example, in the case of the mentioned basic node style, the export needs to be configured as follows:
This creates a self-contained SVG including the external CSS rules which style the nodes.
No CSS transform Changes Allowed
The cssClass
property is added as-is on the root element of the item’s DOM representation. Typically, yFiles for HTML positions
graph items by applying a specific transform on the element.
Therefore, specifying a CSS transform
property interferes with the positioning of elements by the GraphComponent,
and transitions will result in undesired effects when the item is repositioned by the core graph model.
Caveats
There are a couple of things to keep in mind when working with CSS styling for graph items.
Adjusting the visualization of graph items with CSS is purely on a DOM level. yFiles for HTML does not know about these changes. For example, massively increasing the stroke-width of an edge with CSS results in a mismatch between the hit-testing of the style implementation and the visual representation of the edge. This is neglectable in cases where only the color is changed, but may have undesired effects when the item’s outline is affected.
For the same reason, CSS properties on label items that may result in text size changes should be avoided,
since they are not considered for text measuring and therefore might result in wrong text placement.
Especially for labels, only CSS properties that affect visual
aspects of the label’s style should be used.
The actual DOM representation of the library styles may change with major yFiles for HTML releases, but the given CSS class will always be added to the root element. So selecting a specific child element with the root CSS class is discouraged. The GroupNodeStyle and DefaultLabelStyle provide more specific CSS classes for child elements to allow styling of specific aspects of the style implementation.
Changing a property other than the cssClass
property on the style may invalidate the DOM representation such that the
entire DOM subtree may be rebuilt. So additionally changing the CSS class in expectation to trigger a
transition or animation may not work.
For example, changing the label text and the cssClass
in a single rendering cycle does not trigger a transition of the
CSS class. To work around this limitation, it is sufficient to await a render cycle and only update the cssClass
explicitly:
This approach is also shown in the CSS Item Style demo.