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 label="Label" type="x"/>
Loading...

Label Font Size​

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

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

Label Color​

Change the label color with the labelColor property.

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

Label Margin​

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

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

Grid Line​

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

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

Axis Domain Line​

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

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

Providing Data to Axis​

If you use the Axis component alone, without other xy-components, you'll need to 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:

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

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

  return (
    <VisXYContainer data={data}>
      <VisAxis type="x" x={x}/>
    </VisXYContainer>
  )
}
Loading...

Another example:

const x = (d: DataRecord) => d.x * 100
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 tickLine={undefined} type="x"/>
Loading...

Tick Label Font Size​

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

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

Tick Label Color​

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

<VisAxis tickTextColor="#1acb9a" type="x"/>
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...

Label Alignment​

Change the tick's label alignment with respect to the tick marker using tickTextAlign property with a TextAlign value: TextAlign.Left, TextAlign.Right or TextAlign.Center.

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

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 tickTextAngle={15} type="x" tickTextAlign="left"/>
Loading...

Label Width​

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

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

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 tickTextFitMode="trim" type="x" tickTextWidth={10}/>
Loading...

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
  tickTextTrimType="start" 
  type="x" 
  tickTextFitMode="trim" 
  tickTextWidth={30}
/>
Loading...

Force Word Break​

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

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

Text 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 tickTextSeparator="," type="x" tickTextWidth={10}/>
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 numTicks={20} type="x"/>
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 enabed my default), you can use the minMaxTicksOnlyWhenWidthIsLess property (defaults to 250px). This helps avoid clutter in smaller visualizations while still providing essential information.

<VisAxis minMaxTicksOnly={true} type="x"/>
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 1.5​

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...

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...

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
--vis-axis-tick-color: #e8e9ef;
--vis-axis-domain-color: // Unset, falls back to --vis-axis-tick-color;
--vis-axis-tick-label-color: #6c778c;
--vis-axis-grid-color: #e8e9ef;
--vis-axis-label-color: #6c778c;
--vis-axis-tick-label-font-size: 12px;
--vis-axis-tick-label-cursor: default;
--vis-axis-tick-label-text-decoration: none;
--vis-axis-label-font-size: 14px;
--vis-axis-tick-line-width: 1px;
--vis-axis-grid-line-width: 1px;
--vis-axis-domain-line-width: // Unset, falls back to --vis-axis-grid-line-width;
 
/* Dark Theme */
--vis-dark-axis-tick-color: #6c778c;
--vis-dark-axis-domain-color: // Unset, falls back to --vis-dark-axis-tick-color;
--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