Axis options

AxisConfig, AxisFormatter, AxisOptions, AxisPosition and 14 more: generated from the source of active-charts.

Exported by @workspace/active-charts. Generated from the package source; part of the index of every export.

Types#

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

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;
}

AxisFormatter

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

Consumers can opt into stricter typing by picking the appropriate 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).

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

AxisOptions

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

type AxisOptions = AxisOptionsBase & AxisTypeDeclaration;

AxisPosition

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

AxisStyleOptions

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

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;
  };
}

AxisTickValue

Type: 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...") | TimeAxisTickValue | | 'time' | Date objects (continuous time scale) | TimeAxisTickValue | | 'category' | string (the category key) | CategoryAxisTickValue | | 'number' | number | NumberAxisTickValue | | 'log' / 'sqrt' | number | NumberAxisTickValue |

The 'ordinal-time' scale converts all data values to ISO strings internally via .toISOString() (see 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

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

CategoryAxisConfig

AxisConfig narrowed for a category (scaleBand) axis.

The tick formatter value is a string (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).

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

CategoryAxisTickValue

Type: type CategoryAxisTickValue = string;

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

NumberAxisConfig

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

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

NumberAxisTickValue

Type: type NumberAxisTickValue = number;

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

ParentLevelOptions

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.

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

StrokeStyle

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

TemporalAxisType

Type: type TemporalAxisType = 'time' | 'ordinal-time';

The two axis types whose values are dates or times.

TemporalSemantic

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

type TemporalSemantic = 'calendarDate' | 'instant';

TickValues

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

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

TimeAxisConfig

AxisConfig narrowed for a time axis ('time' or 'ordinal-time').

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

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

TimeAxisTickValue

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