Label Styles

Similar to the other graph items, the way labels are rendered is determined by their style. Depending on the style, labels can have custom colors for text and background, different fonts, and custom insets.

Note that the position, angle, and size of a label is determined by its label model parameter. However, since it is the style which determines how to render the label, the style can be asked for a preferred size. The size can be set as the label’s preferredSize.

const size = label.style.renderer.getPreferredSize(label, label.style)
graph.setLabelPreferredSize(label, size)

This is done automatically when a label is added or a new style is set. Note that is up to the label model parameter whether the preferred size is respected, though.

DefaultLabelStyle

The DefaultLabelStyle is a versatile style to render labels. It allows for setting text color, font, and font size. Furthermore, it supports various text alignments and wrapping options. It also supports rendering a background with different border strokes, background colors, and background shapes.

const node1 = graph.createNode([0, 0, 40, 40])
const node2 = graph.createNode([100, 0, 40, 40])
const node3 = graph.createNode([200, 0, 40, 40])

graph.addLabel(node1, 'Text only', ExteriorLabelModel.SOUTH, new DefaultLabelStyle())

graph.addLabel(
  node2,
  'With borders',
  ExteriorLabelModel.SOUTH,
  new DefaultLabelStyle({
    backgroundStroke: 'darkslategray',
    backgroundFill: 'lightgray',
    shape: 'rectangle',
    insets: [2, 0, 2, 0]
  })
)

graph.addLabel(
  node3,
  'Longer texts can be wrapped automatically',
  ExteriorLabelModel.SOUTH,
  new DefaultLabelStyle({
    backgroundStroke: 'darkgoldenrod',
    backgroundFill: 'white',
    shape: 'rectangle',
    insets: [2, 0, 2, 0],
    verticalTextAlignment: 'center',
    horizontalTextAlignment: 'center'
  }),
  new Size(80, 80)
)

Text Rendering Options

DefaultLabelStyle offers a number of properties to determine the text rendering. The most important ones are font, textSize and textFill which define the font, its size and its text color.

The properties horizontalTextAlignment and verticalTextAlignment define the horizontal and vertical position of the text within the label bounds.

Background Rendering Options

The label can be rendered with a background. The backgroundFill and backgroundStroke determine the color of the background and the color and thickness of the border, respectively. Both values can be null.

By default, the label background has a rectangular shape. The shape can be changed using the shape property. Supported values are RECTANGLE, ROUND_RECTANGLE, PILL, HEXAGON.

Note that the irregular shapes are sized in a way that their bounding box fits the overall layout of the label. As a consequence, one has to define insets, otherwise the text will overlap with the borders

CSS Classes

Defining cssClass implicitly provides the following CSS classes as well:

yfiles-label-text

CSS class on the text container element which is either a <text> element or an <g> element in case of right-to-left text rendering.

yfiles-label-background

CSS class on the label’s background element that is created if backgroundStroke or backgroundFill is defined.

You can find more general information about CSS item styling with yFiles for HTML in CSS Item Styles.

Insets and Size

With DefaultLabelStyle it is possible to define insets. These add space between the border and the text. This often increases readability, especially with a visible border or an irregular shape. Note how in the figure below the text overlaps with the hexagon border (middle).

When wrapping is used, the textWrappingShape and textWrappingPadding are considered. When TextWrappingShape.LABEL_SHAPE is used, the text is wrapped inside the shape and those overlaps are avoided as well, so the textWrappingPadding is better suited to keep distance between the text and the label background border.

Although the label size is calculated to fit the text it is sometimes useful to define a minimumSize or maximumSize. That way, it is possible to avoid oddly looking short exceedingly long labels.

For instance, by choosing maximumSize and enabling text wrapping a long text can be automatically wrapped to fit a given width.

Text Wrapping and Clipping

By default, the label size is calculated to fit the text. The text is rendered respecting line breaks if there are any, otherwise as one single line. For given sizes wrapping defines whether the text is wrapped or not. By default, wrapping is disabled.

If the text doesn’t fit into the given layout, the wrapping determines how the text is wrapped and trimmed.

Wrapping affects all but the last line and determines whether a line may be wrapped at any character inside a word (CHARACTER / CHARACTER_ELLIPSIS) or just between words (WORD / WORD_ELLIPSIS).

Trimming only affects the last line and determines whether skipped text, that doesn’t fit into the last line, is indicated by ellipsis (CHARACTER_ELLIPSIS / WORD_ELLIPSIS) or not (CHARACTER / WORD).

Setting clipText to true enforces clipping at the label bounds which only has an effect with TextWrapping.NONE. Other than trimming it might cut in the middle of a character.

The textWrappingShape determines whether wrapping should keep the text inside the rectangular label bounds or inside one of several other predefined shapes that are fit into the label bounds.

The default value TextWrappingShape.RECTANGLE ignores the shape of the background and keeps the text inside rectangular bounds.

When TextWrappingShape.LABEL_SHAPE is used, it considers the shape of the background and keeps the text inside this shape.

An additional padding between the shape and the text can be specified by DefaultLabelStyle.textWrappingPadding.

The remaining TextWrappingShape values correspond to the ShapeNodeShape values with the same name that are used by the ShapeNodeStyle. This means that for matching label and node layouts, matching TextWrappingShape and ShapeNodeShape can be used so that the node shape can be exactly filled with text. The easiest way to use matching layouts is to use an InteriorStretchLabelModel.CENTER.

The following sample code creates two nodes with different shapes with matching labels, which results in the graph below:

const nodePill = graph.createNode(
  new Rect(0, 0, 300, 200),
  new ShapeNodeStyle({
    shape: ShapeNodeShape.PILL,
    fill: Fill.ORANGE,
    stroke: Stroke.BLACK
  })
)
graph.addLabel(
  nodePill,
  longText,
  InteriorStretchLabelModel.CENTER,
  new DefaultLabelStyle({
    font,
    wrapping: 'character',
    shape: LabelShape.PILL
  })
)

const nodeHexagon = graph.createNode(
  new Rect(400, 0, 300, 200),
  new ShapeNodeStyle({
    shape: ShapeNodeShape.HEXAGON,
    fill: Fill.ORANGE,
    stroke: Stroke.BLACK
  })
)
graph.addLabel(
  nodeHexagon,
  longText,
  InteriorStretchLabelModel.CENTER,
  new DefaultLabelStyle({
    font,
    wrapping: 'character',
    shape: LabelShape.HEXAGON
  })
)

graph.createEdge(nodePill, nodeHexagon)

Text Flipping

Labels can be freely rotated, e.g. edge labels which are rendered along the edge. For rotated labels it might happen that the text is upside-down, making it hard to read. If autoFlip is enabled the label will be turned by 180 degrees in these case, making it readable again.

IconLabelStyle

The IconLabelStyle can decorate a label with an icon. The actual label is rendered using a wrapped style.

The property icon determines the icon to render while the icon size is defined in iconSize. Note that iconSize always has to be set to the icon’s size. Otherwise, the icon will not be rendered.

// add a label with an empty text and
// an IconLabelStyle with IconPlacement = InteriorLabelModel.Center
const iconStyleCenter = new IconLabelStyle({
  icon: 'icon.svg',
  iconSize: Size.from([16, 16]),
  iconPlacement: InteriorLabelModel.CENTER
})
graph.addLabel(node, ' ', ExteriorLabelModel.SOUTH, iconStyleCenter)

const iconStyleWest = new IconLabelStyle({
  icon: 'icon.svg',
  iconSize: Size.from([16, 16]),
  iconPlacement: ExteriorLabelModel.WEST
})
graph.addLabel(node, 'Label Text', ExteriorLabelModel.SOUTH, iconStyleWest)

The IconLabelStyle delegates the rendering of the label text and background to a wrapped label style. By default, the wrapped style is a DefaultLabelStyle with its default settings as shown in the middle example in the above image. The rightmost example wraps a DefaultLabelStyle with black border and gray background.

const iconStyle = new IconLabelStyle({
  icon: 'icon.svg',
  iconSize: Size.from([16, 16]),
  wrapped: new DefaultLabelStyle({
    backgroundFill: '#eee',
    backgroundStroke: 'black',
    insets: new Insets(19, 5, 5, 5)
  }),
  iconPlacement: new InteriorLabelModel({ insets: 3 }).createParameter('west')
})
graph.addLabel(node, 'Label Text', ExteriorLabelModel.SOUTH, iconStyle)

The position of the icon relative to the label text is determined by property iconPlacement which takes an ILabelModelParameter. The position of the icon relative to the label bounds is determined in the same way the label model determines the label position relative to the label’s owner node’s bounds. Note that therefore the label model has to be suitable for nodes. InteriorLabelModel and ExteriorLabelModel cover the most common positions.

With ExteriorLabelModel (left in the image above) the icon is placed outside the label bounds and not considered for the label placement. See the differences between the left and the middle example in the image above.

const exteriorStyle = new IconLabelStyle({
  icon: 'icon.svg',
  iconSize: Size.from([16, 16]),
  iconPlacement: InteriorLabelModel.WEST,
  wrapped: new DefaultLabelStyle({ backgroundStroke: Stroke.LIGHT_GRAY })
})
graph.addLabel(node, 'Label Text', ExteriorLabelModel.SOUTH, exteriorStyle)

Note that InteriorLabelModel places the icon inside the label bounds. To avoid the icon overlapping the label text one has to define insets. wrappedInsets lets the wrapped style respect these insets: middle example of the image above: the overall label with the is centered below the node. The rendering of the wrapped style, illustrated by a light gray border, is placed right of the icon.

const interiorStyle = new IconLabelStyle({
  icon: 'icon.svg',
  iconSize: Size.from([16, 16]),
  iconPlacement: InteriorLabelModel.WEST,
  wrappedInsets: new Insets(20, 0, 0, 0),
  wrapped: new DefaultLabelStyle({ backgroundStroke: Stroke.LIGHT_GRAY })
})
graph.addLabel(node, 'Label Text', ExteriorLabelModel.SOUTH, interiorStyle)

Alternatively, the insets can be defined on the wrapped style (see right example in the image above). That way, the wrapped style can render its border around the icon.

const iconStyle = new IconLabelStyle({
  icon: 'icon.svg',
  iconSize: Size.from([16, 16]),
  wrapped: new DefaultLabelStyle({
    backgroundFill: '#eee',
    backgroundStroke: 'black',
    insets: new Insets(19, 5, 5, 5)
  }),
  iconPlacement: new InteriorLabelModel({ insets: 3 }).createParameter('west')
})
graph.addLabel(node, 'Label Text', ExteriorLabelModel.SOUTH, iconStyle)

For multiple icons in one label, an IconLabelStyle can be nested into another with wrapped.

const iconStyleNested = new IconLabelStyle({
  icon: 'icon.svg',
  iconSize: Size.from([16, 16]),
  iconPlacement: InteriorLabelModel.WEST,
  wrappedInsets: new Insets(20, 0, 0, 0),
  wrapped: new IconLabelStyle({
    icon: 'icon.svg',
    iconSize: Size.from([16, 16]),
    iconPlacement: InteriorLabelModel.EAST,
    wrappedInsets: new Insets(20, 0, 0, 0),
    wrapped: new DefaultLabelStyle({ backgroundStroke: Stroke.LIGHT_GRAY })
  })
})
graph.addLabel(node, 'Label with text and two icons', ExteriorLabelModel.SOUTH, iconStyleNested)

Using a node style as label background

yFiles for HTML provides a large number of styles for rendering nodes. The NodeStyleLabelStyleAdapter allows for using these to visualize the background of a label. The label text is visualized using a label style which can be accessed using the labelStyle property of the NodeStyleLabelStyleAdapter.

graph.addLabel(
  edge1,
  'Back',
  null,
  new NodeStyleLabelStyleAdapter({
    labelStyleInsets: new Insets(16, 4, 16, 4),
    nodeStyle: new ShapeNodeStyle({ fill: 'lightgray', shape: 'fat-arrow2' })
  })
)

graph.addLabel(
  edge2,
  'Next',
  null,
  new NodeStyleLabelStyleAdapter({
    labelStyleInsets: new Insets(16, 4, 16, 4),
    nodeStyle: new ShapeNodeStyle({ fill: 'lightgray', shape: 'fat-arrow' })
  })
)

Templates

The TemplateLabelStyle allows for using an SVG snippet as template for the visual representation of labels. Using this style is discussed in detail in the customizing styles section.

Custom Styles

yFiles for HTML offers an abstract style implementation, the LabelStyleBase<TVisual>. Creating custom styles using this class as base class is discussed in detail in section Customizing Styles.

Invisible Labels

The VoidLabelStyle can be used to render a label invisible, while the label is still in the graph. Additionally, the label is not visible to any interactions like mouse clicks.

VoidLabelStyle.INSTANCE provides a singleton of the VoidLabelStyle.

graph.setStyle(invisibleLabel, VoidLabelStyle.INSTANCE)