Backdrops

Backdrops are styled GPU shapes drawn around a node and, optionally, its label. They support a fill color, border, drop shadow, corner radius, and configurable coverage area. They are designed to make a node visually stand out from the rest of the graph.

Because a backdrop is a fully styled shape rendered per element, it is expensive compared to other node properties. It is meant for a handful of elements at a time (typically the hovered or otherwise highlighted node, not for every node in the graph).

Backdrops vs. label backgrounds

Both render a shape behind nodes or labels, but they sit on opposite ends of a tradeoff. Backdrops are a styled GPU shape (shadow, border, corner radius, configurable area). They are expensive, meant for a handful of elements at a time, and typically tied to hover or highlight states. Label backgrounds (labelBackgroundColor, labelBackgroundPadding) are a flat colored rect behind label text. They are cheap, intended to be always-on, and also the hit area for label events when nodeLabelEvents / edgeLabelEvents is enabled.

Properties

Backdrops are controlled via flat backdrop* style properties:

Property	Type	Description
backdropVisibility	"visible" | "hidden"	Whether the backdrop is shown
backdropColor	string	Fill color
backdropPadding	number	Padding around the node and label (px)
backdropCornerRadius	number	Corner radius (px)
backdropBorderColor	string	Border color
backdropBorderWidth	number	Border width (px)
backdropShadowColor	string	Shadow color
backdropShadowBlur	number	Shadow blur radius (px)
backdropLabelPadding	number	Separate padding for the label portion (-1 falls back to backdropPadding)
backdropArea	"both" | "node" | "label"	Which area the backdrop covers

import Graph from "graphology";
import Sigma from "sigma";
import { layerFill, sdfCircle, sdfDiamond, sdfSquare, sdfTriangle } from "sigma/rendering";
import { DEFAULT_STYLES } from "sigma/types";

import { registerControls } from "../_controls";

const container = document.getElementById("sigma-container") as HTMLElement;

const {
  backdropDisplay,
  backdropPadding,
  backdropCornerRadius,
  backdropBorderWidth,
  backdropShadowBlur,
  backdropLabelPadding,
} = registerControls({
  backdropDisplay: {
    type: "select",
    label: "Display",
    default: "always",
    options: [
      { label: "Always", value: "always" },
      { label: "On hover", value: "hover" },
      { label: "Hidden", value: "hidden" },
    ],
  },
  backdropPadding: { type: "number", label: "Padding (px)", default: 6, min: 0, max: 20, step: 1 },
  backdropCornerRadius: { type: "number", label: "Corner radius (px)", default: 0, min: 0, max: 20, step: 1 },
  backdropBorderWidth: { type: "number", label: "Border width (px)", default: 0, min: 0, max: 8, step: 0.5 },
  backdropShadowBlur: { type: "number", label: "Shadow blur (px)", default: 12, min: 0, max: 30, step: 1 },
  backdropLabelPadding: { type: "number", label: "Label padding (px)", default: -1, min: -1, max: 20, step: 1 },
});

const nodes = [
  { id: "a", x: 0, y: 0, size: 12, shape: "circle", labelPosition: "right", label: "Circle / right" },
  { id: "b", x: 200, y: 0, size: 16, shape: "square", labelPosition: "above", label: "Square / above" },
  { id: "c", x: 400, y: 0, size: 14, shape: "diamond", labelPosition: "below", label: "Diamond / below" },
  { id: "d", x: 600, y: 0, size: 14, shape: "triangle", labelPosition: "over", label: "Triangle / over" },
  { id: "e", x: 100, y: -120, size: 10, shape: "circle", labelPosition: "left", label: "Circle / left" },
  { id: "f", x: 300, y: -120, size: 18, shape: "square", labelPosition: "right", label: "Square / right" },
  { id: "g", x: 500, y: -120, size: 12, shape: "diamond", labelPosition: "above", label: "Diamond / above" },
] as const;

const graph = new Graph();
for (const node of nodes) {
  graph.addNode(node.id, node);
}

const backdropVisibility =
  backdropDisplay === "hover"
    ? { whenState: "isHovered" as const, then: "visible" as const, else: "hidden" as const }
    : backdropDisplay === "hidden"
      ? ("hidden" as const)
      : ("visible" as const);

new Sigma(graph, container, {
  primitives: {
    nodes: {
      shapes: [sdfCircle(), sdfSquare(), sdfDiamond(), sdfTriangle()],
      layers: [layerFill()],
    },
  },
  styles: {
    nodes: [
      DEFAULT_STYLES.nodes,
      {
        size: { attribute: "size", defaultValue: 10 },
        shape: { attribute: "shape", defaultValue: "circle" },
        labelPosition: { attribute: "labelPosition", defaultValue: "right" },
      },
      {
        backdropVisibility,
        backdropColor: "white",
        backdropShadowColor: "rgba(0, 0, 0, 0.5)",
        backdropShadowBlur,
        backdropPadding,
        backdropBorderColor: "black",
        backdropBorderWidth,
        backdropCornerRadius,
        backdropLabelPadding,
        backdropArea: "both",
        zIndex: 1,
      },
    ],
  },
  settings: {
    itemSizesReference: "positions",
    zoomToSizeRatioFunction: (x: number) => x,
    autoRescale: true,
  },
});

Result Source

View source Open