Skip to main content

Axis

Basic configuration​

The Axis component has been designed to work together with XY Container. The minimal Axis configuration looks like:

<VisAxis type="x"/>
Loading...

Axis Types​

Axis supports two AxisType properties to bind to your data: AxisType.X and AxisType.Y. You can also simply provide the string "x" or "y".

AxisType.X​

<VisAxis type="x"/>
Loading...

AxisType.Y​

<VisAxis type="y"/>
Loading...

Axis Position​

You can change the position of your axis with a Position type or a string equivalent: "top", "right", "bottom", or "left".

component.tsx
<VisXYContainer data={data}>
  <VisAxis type="y" position="right" label="Y"/>
  <VisAxis type="x" position="top" label="X"/>
</VisXYContainer>
Loading...
note

Note: An X Axis can only accept the values Position.Bottom (default) and Position.Top and a Y Axis can only accept Position.Left (default) and Position.Right. The default will be used in the case of an invalid position argument.

Labeling​

Axis Label​

You can provide a string to label your axes with the label property:

<VisAxis type="x" label="Label"/>
Loading...

Label Font Size​

Change the label size (in pixels) with the labelFontSize property.

<VisAxis type="x" label="Label" labelFontSize={30}/>
Loading...

Label Color​

Change the label color with the labelColor property.

<VisAxis type="x" label="Label" labelColor="#1acb9a"/>
Loading...

Label Margin​

The spacing between the label and the axis itself can be set with the labelMargin property:

<VisAxis type="x" label="Label" labelMargin={5}/>
Loading...

Label Text Separator​

When a label is too long to fit, Axis wraps it onto multiple lines (this happens when labelTextFitMode is set to FitMode.Wrap, which is the default). You can control where the text is allowed to break by providing the labelTextSeparator property with a string or string[] of separators. By default the label breaks on spaces, hyphens, periods and commas.

In the example below the label contains none of the default separators, so it can't wrap and overflows the axis. Provide "/" as the separator to let it break on the slashes instead.

<VisAxis
  type="y" 
  label="Population/Density/Per/Square/Kilometer" 
  labelTextSeparator="/"
/>
Loading...

Grid Line​

You can enable or disable the visibility of the Axis grid line with the gridLine property.

<VisAxis type="x" gridLine={true}/>
Loading...

Axis Domain Line​

You can enable or disable the visibility of the axis domain line with the domainLine property.

<VisAxis type="x" label="Label" domainLine={true}/>
Loading...

Tick Configuration​

The Axis component supports a wide variety of tick customization options

Tick Line​

You can remove tick labels from your axis by setting the tickLine property to false:

<VisAxis type="x" tickLine={undefined}/>
Loading...

Tick Size​

Control the length of the tick marks (in pixels) with the tickSize property. It accepts a single number, which applies to both inner and outer ticks, or a [innerTickSize, outerTickSize] tuple to set them independently. The default value is 6.

<VisAxis type="x" tickSize={6}/>
Loading...

Tick Label Font Size​

To change the font size for the tick labels, you provide the tickTextFontSize property with a CSS string.

<VisAxis type="x" tickTextFontSize="50px"/>
Loading...

Tick Label Color​

You can change the color of the tick labels with the tickTextColor property.

<VisAxis type="x" tickTextColor="#1acb9a"/>
Loading...

Tick Label Format​

You can customize how ticks are formatted using the tickFormat property and a label formatter function. The following example uses Javascript's built-in Date formatter function toDateString().

<VisAxis type="x" x={x} tickFormat={tickFormat}/>
Loading...

Tick Label Alignment​

Change the tick's label alignment with respect to the tick marker using tickTextAlign. It accepts a constant TextAlign value (TextAlign.Left, TextAlign.Right or TextAlign.Center) or a function for per-tick control. The function receives (tickValue, tickIndex, ticksValues, tickPosition, componentWidth, componentHeight) and should return a TextAlign value.

<VisAxis type="x" tickTextAlign="right"/>
Loading...

Tick Label Rotation​

Change the tick's label angle using tickTextAngle property with a number value. Use this variable along with tickTextAlign to make sure the tick label displays as desired.

<VisAxis type="x" tickTextAlign="left" tickTextAngle={15}/>
Loading...

Tick Label Width​

To limit the width of the tick labels (in pixels), you can use the tickTextWidth property.

<VisAxis type="x" tickTextWidth={50}/>
Loading...

Tick Label Fit Mode​

Axis accepts the following values for the tickTextFitMode property: FitMode.Wrap or FitMode.Trim. This determines how the axis will handle tick text overflow. The following example showcases the previous example using "trim" instead of "wrap".

<VisAxis type="x" tickTextWidth={10} tickTextFitMode="trim"/>
Loading...

Tick Label Trim Type​

When a tick label becomes too long, and you want to trim it, you can customize the trimming method with the tickTextTrimType property. Axis accepts a TrimMode or a string. For example, when we configure tickTextTrimType to TrimMode.Start, we can see the start of the label gets cut off instead of the middle.

<VisAxis
  type="x" 
  tickTextFitMode="trim" 
  tickTextWidth={30} 
  tickTextTrimType="start"
/>
Loading...

Force Word Break​

In addition, you can enable a forced word break for overflowing tick labels with the tickTextForceWordBreak property.

<VisAxis type="x" tickTextWidth={10} tickTextForceWordBreak={true}/>
Loading...

Tick Label Separator​

Axis accepts a string or string[] value for tickTextSeparator property. This will allow tick labels to be separated by custom values in the case of overflow. Note: this only takes effect when FitMode.Wrap is enabled and tickTextWidth is defined.

<VisAxis type="x" tickTextWidth={10} tickTextSeparator=","/>
Loading...

Custom Number of Ticks​

By default, the Axis component provides an optimal number of ticks displayed based on the component's size. You can alter the tick count to your liking using the numTicks property.

note

The specified count is only a hint, the axis can have more or fewer ticks depending on the data

<VisAxis type="x" numTicks={20}/>
Loading...

Tick Spacing new​

When numTicks is not set, the Axis derives the tick count from the component's size. For the X axis, the tickSpacing property controls that density by setting the approximate distance between ticks in pixels (default: 175). Smaller values pack in more ticks; larger values spread them out.

note

tickSpacing only applies to the X axis, and is ignored when numTicks is set explicitly.

<VisAxis type="x" tickSpacing={175}/>
Loading...

Display Only Minimum and Maximum Ticks​

Set the minMaxTicksOnly property to true if you only want to see the two end ticks on the axis.

note

To display the minimum and maximum ticks only when the chart width is limited (this behavior is enabled my default), you can use the minMaxTicksOnlyWhenWidthIsLess property (defaults to 250px). This helps avoid clutter in smaller visualizations while still providing essential information.

<VisAxis type="x" minMaxTicksOnly={true}/>
Loading...

When using minMaxTicksOnly, you can still show grid lines by setting minMaxTicksOnlyShowGridLines to true.

<VisAxis
  minMaxTicksOnly={true} 
  type="x" 
  minMaxTicksOnlyShowGridLines={true}
/>
Loading...

Set Ticks Explicitly​

You can customize the ticks displayed by providing the Axis component with a number array. The following example only shows even values for x after getting the tickValue array from a filter function.

function tickValues() {
  return data.filter(d => d.x % 2 == 0)
})
<VisAxis type="x" tickValues={[0,2,4,6,8]}/>
Loading...

Hide Overlapping Ticks​

To prevent overlapping tick labels on the axis, you can use the tickTextHideOverlapping property. When enabled, it hides any tick labels that would otherwise overlap with one another based on a simple bounding box collision detection algorithm. This ensures cleaner, more legible axes, particularly in cases where the available space is limited or when displaying many ticks.

note

The algorithm used for detecting overlaps may not be accurate when a tickTextAngle is specified, so results can vary depending on tick rotation.

<VisAxis type="x" numTicks={15} tickTextHideOverlapping={true}/>
Loading...

Adaptive Tick Sets new​

Set tickTextAdaptiveSets to true to let the Axis pick the number of ticks automatically so that their labels never overlap. The axis measures candidate tick sets off-screen and renders the largest "nice" set that fits, degrading to sparser sets on narrower charts. Ticks left out of the fitted set still render as unlabeled tick marks, so the axis scale stays visually intact.

numTicks (or, when it's not set, the width-based default derived from tickSpacing) acts as the upper bound on the number of labeled ticks.

Toggle the checkbox below to see how enabling tickTextAdaptiveSets resolves the overlap on a dense, wide-range axis:

<VisAxis type="x" numTicks={20} tickTextAdaptiveSets={true}/>
Loading...

When explicit tickValues are provided, the axis instead fits every-k-th subset of them (every value, then every 2nd, every 3rd, and so on), anchored at the first value so the labeled ticks stay evenly spaced.

note

tickTextAdaptiveSets takes over the narrow-width behavior: it disables the width-based minMaxTicksOnlyWhenWidthIsLess fallback, and has no effect when minMaxTicksOnly is enabled.

tip

When tickTextAdaptiveSets is enabled, you don't need to also set tickTextHideOverlapping. The adaptive pass already measures label overlap and only labels the ticks that fit, so no labels overlap in the first place.

Displaying Multiple Axes​

More commonly, you will want to display both an x and y axis for your graph. You can display multiple axes in an XY Container like so:

component.tsx
<VisXYContainer data={data}>
  <VisAxis type="y"/>
  <VisAxis type="x"/>
</VisXYContainer>
Loading...

Displaying Axis with a Chart​

You can include a chart within your XY Container alongside your axes like this:

component.tsx
<VisXYContainer data={data}>
  <VisAxis type="y"/>
  <VisLine x={x} y={y}/>
  <VisAxis type="x"/>
</VisXYContainer>
Loading...

Using Axis Alone​

If you use the Axis component alone, without other xy-components, you can provide an x accessor or y accessors to populate the axis values. Consider the following example with a single axis and a data array with x values in the range 0 < x < 10:

<VisAxis type="x" x={x}/>
Loading...

Alternatively, you can set the xDomain or yDomain property on XYContainer to set the domain of the axis:

component.tsx
import { VisXYContainer, VisAxis } from '@unovis/react'

function Component(props) {
  const data: DataRecord[] = props.data

  return (
    <VisXYContainer xDomain={[0,15]} data={data}>
      <VisAxis type="x"/>
    </VisXYContainer>
  )
}
Loading...

Additional Styling: CSS Variables​

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

styles.css
.container {
  --vis-axis-tick-label-font-size: 20px;
  --vis-axis-label-color: #1acb9a;
  --vis-axis-font-family: monospace;
  --vis-axis-tick-label-color:  #8777d9;
}
Loading...
All supported CSS variables and their default values
--vis-axis-font-family: undefined;
--vis-axis-tick-color: #e8e9ef;
--vis-axis-domain-color: undefined;
--vis-axis-domain-line-dasharray: undefined;
--vis-axis-grid-color: #e8e9ef;
--vis-axis-grid-line-width: 1px;
--vis-axis-grid-line-dasharray: none;
--vis-axis-grid-opacity: 1;
--vis-axis-grid-transition: none;
--vis-axis-label-font-size: 14px;
--vis-axis-label-color: #6c778c;
--vis-axis-label-weight: 500;
--vis-axis-tick-label-color: #6c778c;
--vis-axis-tick-label-font-size: 12px;
--vis-axis-tick-label-weight: 500;
--vis-axis-tick-label-cursor: default;
--vis-axis-tick-label-text-decoration: none;
--vis-axis-tick-line-width: 1px;
--vis-axis-tick-label-hide-transition: opacity 400ms ease-in-out;
--vis-axis-domain-line-width: undefined;
--vis-dark-axis-tick-color: #6c778c;
--vis-dark-axis-domain-color: undefined;
--vis-dark-axis-tick-label-color: #e8e9ef;
--vis-dark-axis-grid-color: #6c778c;
--vis-dark-axis-label-color: #fefefe;

Events​

import { Axis } from '@unovis/ts'

events = {
  [Axis.selectors.tick]: {
    mouseover: (d: number | Date) => {},
    mouseout: (d: number | Date) => {}
  }
}
<VisAxis type="x" events={events}/>

Component Props​

NameTypeDescription
* required property