Skip to main content

Plotband

Plotband is used to highlight a particular region in charts along Y or X axis. It is compatible only with XY container.

Basic configuration​

component.tsx
<VisXYContainer data={data}>
  <VisLine x={x} y={y}/>
  <VisAxis type="x"/>
  <VisAxis type="y"/>
  <VisPlotband from={1} to={5} axis="x"/>
</VisXYContainer>
Loading...

Orientation​

The axis property determines whether the plotband is drawn horizontally or vertically, based on the axis it targets.

  • axis: x draws a vertical plotband that spans across the y-axis — typically used to highlight a range of x-values (e.g., time periods).
  • axis: y (default) draws a horizontal plotband that spans across the x-axis — commonly used to highlight a range of y-values (e.g., thresholds or danger zones).

Use this setting to match the orientation of the plotband with the dimension of interest in your chart.

Default: y (horizontal)

component.tsx
<VisXYContainer data={data}>
  <VisLine x={x} y={y}/>
  <VisAxis type="x"/>
  <VisAxis type="y"/>
  <VisPlotband from={6} to={7}/>
</VisXYContainer>
Loading...

Color​

The color property sets the fill color of the plotband.

You can provide any valid CSS color value, such as:

  • Named colors (e.g., "red", "blue")
  • Hex codes (e.g., "#ffcc00")
  • RGB / RGBA (e.g., "rgba(255, 0, 0, 0.3)")
  • CSS variables (e.g., var(--vis-plotband-color))

Use this to visually distinguish different plotbands or to align them with your chart’s color theme.

Default: var(--vis-plotband-color)

component.tsx
<VisXYContainer data={data}>
  <VisLine x={x} y={y}/>
  <VisAxis type="x"/>
  <VisAxis type="y"/>
  <VisPlotband
    from={6} 
    to={7} 
    axis="x" 
    color="rgba(245, 40, 145, 0.2)"
  />
</VisXYContainer>
Loading...

Range​

The from and to properties define the start and end coordinates of the plotband along the specified axis. These values determine the area to be highlighted:

  • from marks the starting point.
  • to marks the ending point.
  • Both must be set for the plotband to render.
  • If from and to are equal, no area is drawn.
  • If either is null or undefined, the plotband is skipped.

Default:0 for both

component.tsx
<VisXYContainer data={data}>
  <VisLine x={x} y={y}/>
  <VisAxis type="x"/>
  <VisAxis type="y"/>
  <VisPlotband
    from={6} 
    to={7} 
    axis="x" 
    color="rgba(245, 40, 145, 0.2)"
  />
  <VisPlotband
    from={4} 
    to={7} 
    axis="y" 
    color="rgba(40, 200, 80, 0.2)"
  />
</VisXYContainer>
Loading...
note

The specified plotband range should be included in the corresponding axis domain.

Labeling​

Plotband support an optional label to annotate the highlighted area. The labeling system is flexible and includes controls for positioning, orientation, offset, size, and color.

Label Position​

The label can be positioned relative to the plotband rectangle using the labelPosition property. It supports a variety of placements such as inside or outside each side of the plotband area.

Available values include:

  • top-left-inside, top-left-outside
  • top-inside, top-outside
  • top-right-inside, top-right-outside
  • right-inside, right-outside
  • bottom-right-inside, `bottom-right-outside'
  • bottom-inside, bottom-outside
  • bottom-left-inside, bottom-left-outside
  • left-inside, left-outside

These positions determine the base placement of the label before any offset or orientation is applied.

component.tsx
<VisXYContainer data={data}>
  <VisLine x={x} y={y}/>
  <VisAxis type="x"/>
  <VisAxis type="y"/>
  <VisPlotband
    from={6} 
    to={7} 
    axis="x" 
    labelText="Label" 
    labelPosition="top-left-inside"
  />
</VisXYContainer>
Loading...

Label Orientation​

Use the labelOrientation property to control the rotation of the label text. You can choose between:

  • horizontal (default)
  • vertical

This setting helps optimize readability depending on the label’s placement.

component.tsx
<VisXYContainer data={data}>
  <VisLine x={x} y={y}/>
  <VisAxis type="x"/>
  <VisAxis type="y"/>
  <VisPlotband
    from={6} 
    to={7} 
    axis="x" 
    labelText="Label" 
    labelOrientation="vertical"
  />
</VisXYContainer>
Loading...

Label Offset​

You can adjust the label’s position with pixel-based offsets using the labelOffsetX and labelOffsetY properties. These apply additional horizontal and vertical shifts from the base position.

For example:

  • A positive labelOffsetX will move the label further right.
  • A negative labelOffsetY will shift it upward.
component.tsx
<VisXYContainer data={data}>
  <VisLine x={x} y={y}/>
  <VisAxis type="x"/>
  <VisAxis type="y"/>
  <VisPlotband
    from={6} 
    to={7} 
    axis="x" 
    labelText="Label" 
    labelOffsetX={50} 
    labelOffsetY={30}
  />
</VisXYContainer>
Loading...

This is useful for fine-tuning alignment or preventing overlap with other visual elements.

Label Font Size​

The labelSize property controls the font size of the label, specified in pixels.

By default, it uses the CSS variable --vis-plotband-label-font-size, which resolves to 12px. You can override this by providing a number (e.g., 14 for 14px).

component.tsx
<VisXYContainer data={data}>
  <VisLine x={x} y={y}/>
  <VisAxis type="x"/>
  <VisAxis type="y"/>
  <VisPlotband
    from={6} 
    to={7} 
    axis="x" 
    labelText="Label" 
    labelSize={26}
  />
</VisXYContainer>
Loading...

Label Color​

To customize the label’s appearance, use the labelColor property. This accepts any valid CSS color string such as:

  • Named colors: red, black
  • Hex values: #333, #FF8800
  • CSS variables: var(--vis-text-color)

If omitted, the label inherits the default text color for the plotband context.

component.tsx
<VisXYContainer data={data}>
  <VisLine x={x} y={y}/>
  <VisAxis type="x"/>
  <VisAxis type="y"/>
  <VisPlotband
    from={6} 
    to={7} 
    axis="x" 
    labelText="Label" 
    labelColor="#ff8400"
  />
</VisXYContainer>
Loading...

CSS Variables​

The Plotband component supports additional styling via CSS variables that you can define for your visualization container. For example:

styles.css
.custom-plotband {
  --vis-plotband-color: rgba(255, 174, 0, 0.25);
  --vis-plotband-label-font-size: 20px;
  --vis-plotband-label-color: #ff6600;
}
component.tsx
<VisXYContainer data={data}>
  <VisLine x={x} y={y}/>
  <VisAxis type="x"/>
  <VisAxis type="y"/>
  <VisPlotband from={1} to={5} axis="x" labelText="Label 🙂"/>
</VisXYContainer>
Loading...
Supported CSS variables and their default values
--vis-plotband-color: rgba(255, 255, 90, 0.2);
--vis-plotband-label-font-size: 12px;
--vis-plotband-label-color: #000;

/* Dark Theme */
--vis-dark-plotband-color: rgba(220, 220, 90, 0.2);
--vis-dark-plotband-label-color: #e5e9f7;

Component Props​

NameTypeDescription
* required property