---
id: "packages/active-charts/all-exports/axis-options"
title: "Axis options"
description: "AxisConfig, AxisFormatter, AxisOptions, AxisPosition and 14 more: generated from the source of active-charts."
url: "/packages/active-charts/all-exports/axis-options"
locale: "en"
revision: "g0mvjxwj5c-88bdbe1c:axis-options"
---

# Axis options

Exported by `@workspace/active-charts`. Generated from the package source; part of [the index of every export](/packages/active-charts/all-exports).

## Types

**AxisConfig**

```ts
interface AxisConfig {
  type?: AxisType;
  temporalSemantic?: TemporalSemantic;
  valueSemantics?: ChartValueSemantics;
  position?: AxisPosition;
  title?: string;
  formatter?: AxisFormatter;
  format?: string;
  tickCount?: number;
  tickInterval?: number;
  targetPixelInterval?: number;
  minPixelInterval?: number;
  min?: number;
  max?: number;
  softMin?: number;
  softMax?: number;
  nice?: boolean;
  rotation?: number;
  autoRotate?: boolean;
  maxLabelWidth?: number;
  truncate?: boolean;
  wrap?: number;
  tickValues?: TickValues;
  reversed?: boolean;
  style?: AxisStyleOptions;
  gridLine?: {
    enabled?: boolean;
    style?: StrokeStyle;
  };
  parentLevel?: boolean | ParentLevelOptions;
}
```

High-level axis configuration for chart wrappers.
Compiles down to AxisOptions internally.

**AxisFormatter**

```ts
type AxisFormatter<V extends AxisTickValue = AxisTickValue> = (
  value: V,
  index?: number,
  allValues?: V[],
) => string;
```

Reusable axis formatter signature, parameterised by tick-value runtime type.

Consumers can opt into stricter typing by picking the appropriate
{@link AxisTickValue} alias. Defaults to the widest union so that
`(v) => …` and `(v: unknown) => …` call-sites type-check.

The optional `index` and `allValues` arguments enable boundary-aware
decisions — e.g. show the year only on the first tick, or whenever
the year changes between ticks. `(value) => string` formatters remain
compatible (the extra arguments are ignored).

**AxisOptions**

```ts
type AxisOptions = AxisOptionsBase & AxisTypeDeclaration;
```

The internal axis configuration of `<Chart>`. A `'time'` or `'ordinal-time'`
axis declares its {@link TemporalSemantic}; no other axis does.

**AxisPosition**

```ts
type AxisPosition = 'top' | 'right' | 'bottom' | 'left';
```

**AxisStyleOptions**

```ts
interface AxisStyleOptions {
  line?: {
    stroke?: string;
    strokeWidth?: number;
    visible?: boolean;
  };
  tick?: {
    stroke?: string;
    length?: number;
  };
  label?: {
    fill?: string;
    fontSize?: number;
    fontFamily?: string;
    fontWeight?: number | string;
  };
  title?: {
    fill?: string;
    fontSize?: number;
    fontFamily?: string;
    fontWeight?: number | string;
  };
}
```

Axis-level styling overrides. Each sub-object overrides theme defaults
for the corresponding axis element. Mirrors the `TooltipOptions.style`
pattern — a single flat object with sub-categories (no deep nesting).

**AxisTickValue**

```ts
type AxisTickValue = Date | string | number;
```

Union of possible tick-value runtime types passed to axis formatters.

The actual type depends on the axis-type the formatter is bound to:

| Axis type | Runtime value | Helper alias |
| ---------------- | ------------------------------------------ | ----------------------- |
| `'ordinal-time'` | ISO date string (`"2024-01-15T..."`) | {@link TimeAxisTickValue} |
| `'time'` | `Date` objects (continuous time scale) | {@link TimeAxisTickValue} |
| `'category'` | `string` (the category key) | {@link CategoryAxisTickValue} |
| `'number'` | `number` | {@link NumberAxisTickValue} |
| `'log'` / `'sqrt'` | `number` | {@link NumberAxisTickValue} |

The `'ordinal-time'` scale converts all data values to ISO strings
internally via `.toISOString()` (see {@link
https://github.com/d3/d3-scale|d3-scale}). Consumers should treat
the formatter `value` as a string in this case and use
`formatDate(value, ...)` from `@workspace/active-format`
which handles strings via `parseISO`.

**AxisType**

```ts
type AxisType =
  'number' | 'log' | 'sqrt' | 'time' | 'ordinal-time' | 'category';
```

**CategoryAxisConfig**

```ts
type CategoryAxisConfig = Omit<
  AxisConfig,
  'type' | 'formatter' | 'temporalSemantic' | 'softMin' | 'softMax'
> & {
  type?: 'category';
  temporalSemantic?: never;
  formatter?: AxisFormatter<CategoryAxisTickValue>;
};
```

{@link AxisConfig} narrowed for a `category` (`scaleBand`) axis.

The tick `formatter` value is a `string` ({@link CategoryAxisTickValue}):
`scaleBand` stringifies its domain, so a date passed here is rendered as
a non-ISO string. Typing the value as `string` makes `formatDate(v, ...)`
and `v as Date` fail to compile, closing the date-on-category trap. The
`type` is pinned to `'category'` (optional, since this is the default for
bar-class wrappers).

**CategoryAxisTickValue**

```ts
type CategoryAxisTickValue = string;
```

Runtime value type for `'category'` axis formatters (the category key).

**NumberAxisConfig**

```ts
type NumberAxisConfig = Omit<
  AxisConfig,
  'type' | 'formatter' | 'temporalSemantic' | 'wrap'
> & {
  type?: 'number' | 'log' | 'sqrt';
  temporalSemantic?: never;
  formatter?: AxisFormatter<NumberAxisTickValue>;
};
```

{@link AxisConfig} narrowed for a numeric axis (`'number'`, `'log'`, or
`'sqrt'`). The tick `formatter` value is a `number`
({@link NumberAxisTickValue}).

**NumberAxisTickValue**

```ts
type NumberAxisTickValue = number;
```

Runtime value type for `'number'` / `'log'` / `'sqrt'` axis formatters.

**ParentLevelOptions**

```ts
interface ParentLevelOptions {
  enabled?: boolean;
  formatter?: (value: unknown) => string;
  fill?: string;
  fontSize?: number;
  fontWeight?: number | string;
  showTicks?: boolean;
}
```

Configuration for hierarchical "parent level" axis labels — a second
row of labels under the main ticks that shows the next-coarser
calendar unit (e.g. years under months, months under days).

Inspired by AG Charts' `parentLevel` and Highcharts' second-pass
`dateTimeLabelFormats`. Opt-in on every axis type: enable with the
boolean shorthand `parentLevel: true` or pass an options object to
customise. Omitted (or `false`) leaves the second row disabled.

**StrokeStyle**

```ts
interface StrokeStyle {
  stroke?: string;
  strokeWidth?: number;
  lineDash?: number[];
}
```

**TemporalAxisType**

```ts
type TemporalAxisType = 'time' | 'ordinal-time';
```

The two axis types whose values are dates or times.

**TemporalSemantic**

```ts
type TemporalSemantic = 'calendarDate' | 'instant';
```

What the values of a temporal axis ARE. Required on every
`'time'` and `'ordinal-time'` axis; there is no default.

- `'calendarDate'`: a calendar day (a trading day, a reporting date, a
month). The day never moves: `2026-01-01` is 1 January in every zone. The
day is read from the value itself: a `YYYY-MM-DD` or ISO string by its
date part, a `Date` or timestamp by its UTC fields (the storage convention
of a calendar day). Language and notation still follow the chart
presentation.
- `'instant'`: a point in time (a page view, a login). Its day and time are
read in the chart presentation's zone, so the same value can fall on
another day in another zone.

The same declaration governs every surface that shows the axis value: tick
labels, the parent row, the tooltip, the crosshair, the screen-reader table
and the keyboard announcement. A custom `label.formatter` receives the raw
value and must read it the same way (`formatDateOnly` for a calendar date).

**TickValues**

```ts
type TickValues = unknown[] | ((domain: unknown[]) => unknown[]);
```

Custom tick values. Either a fixed array of values, or a callback that
receives the resolved domain and returns the tick values.

**TimeAxisConfig**

```ts
type TimeAxisConfig = Omit<
  AxisConfig,
  'type' | 'formatter' | 'temporalSemantic' | 'wrap' | 'softMin' | 'softMax'
> & {
  type?: TemporalAxisType;
  temporalSemantic: TemporalSemantic;
  formatter?: AxisFormatter<TimeAxisTickValue>;
};
```

{@link AxisConfig} narrowed for a time axis (`'time'` or `'ordinal-time'`).

The tick `formatter` value is a `Date | string` ({@link TimeAxisTickValue}):
`'time'` yields `Date`, `'ordinal-time'` yields ISO strings;
`formatDate(value, ...)` accepts both via `parseISO`.

**TimeAxisTickValue**

```ts
type TimeAxisTickValue = Date | string;
```

Runtime value type for `'time'` / `'ordinal-time'` axis formatters.

Includes both `Date` (continuous time scale) and `string` (ordinal-time
scale ISO strings). Use with `formatDate(value, ...)` from
`@workspace/active-format` which handles both via `parseISO`.