--- id: "packages/active-charts/all-exports/series-options" title: "Series options" description: "AreaSeriesOptions, BarLabelOptions, BarLabelPosition, BarSeriesOptions and 19 more: generated from the source of active-charts." url: "/packages/active-charts/all-exports/series-options" locale: "en" revision: "g0mvjxwj5c-88bdbe1c:series-options" --- # Series options Exported by `@workspace/active-charts`. Generated from the package source; part of [the index of every export](/packages/active-charts/all-exports). ## Types **AreaSeriesOptions** ```ts interface AreaSeriesOptions extends SeriesOptionsBase { type: 'area'; fill?: string; fillOpacity?: number; stroke?: string; strokeWidth?: number; gradient?: boolean; stacked?: boolean; stackedPercentage?: boolean; stackGroup?: string; marker?: MarkerOptions; connectMissingData?: boolean; curve?: CurveType; label?: PointLabelOptions; zones?: SeriesZones; } ``` **BarLabelOptions** ```ts interface BarLabelOptions extends Omit { position?: BarLabelPosition; } ``` The value labels of a bar series (T9): {@link LabelOptions} with the bar's four places. A label at `'inside-end'` or `'inside-base'` needs its length plus `offset` inside the bar along the value direction, and the label colour must read on the bar; otherwise `fallback: 'auto'` moves it outside (a stack segment's label is hidden instead) and `'hide'` hides it. A stack segment's ends are its own, never the stack's: the stack's end carries `stackTotal`. **BarLabelPosition** ```ts type BarLabelPosition = 'inside' | 'outside' | 'inside-end' | 'inside-base'; ``` Where a bar's value label goes (CF1, T9). `'outside'` (default) beyond the bar's value end; `'inside'` centred in the bar; `'inside-end'` inside, against its VALUE end; `'inside-base'` inside, against its BASE (zero, or the segment's own base on a stack). The ends are semantic: a negative bar's value end is the end its value points to, and a reversed axis keeps the roles, wherever the pixels put them. **BarSeriesOptions** ```ts interface BarSeriesOptions extends SeriesOptionsBase, BarSizingOptions { type: 'bar'; fill?: string; stroke?: string; paint?: DatumPaintResolver; cornerRadius?: number; grouped?: boolean; stacked?: boolean; stackedPercentage?: boolean; stackGroup?: string; stackTotal?: StackTotalOptions; errorBars?: ErrorBarOptions; horizontal?: boolean; label?: BarLabelOptions; } ``` **BarSizingOptions** ```ts interface BarSizingOptions { widthRatio?: number; maxWidth?: number; } ``` How wide a bar draws across its category (CF1). Read by bar, waterfall and range-bar series. Both fields are optional; without them Active sizes the bars itself (a deliberate column, never a slab: W-VQ-3). Bars shrink, they never overflow: a bar draws `maxWidth` where its share of the category has room for it, and narrower where it has not, down to one pixel; no bar is dropped and none draws wider than its share. On a chart with several bar series the bars of one category form one group, sized as a whole and centred; the first bar series that declares a field decides it for the group. **CurveType** ```ts type CurveType = 'linear' | 'monotone' | 'catmullRom' | 'step' | 'stepBefore' | 'stepAfter'; ``` Curve interpolation type for line/area series. **EndpointLabelOptions** ```ts interface EndpointLabelOptions extends PointLabelOptions { endpoints?: 'both' | 'low' | 'high'; } ``` The labels of a mark with two ends (BC-LB1): a range bar, a range area or a dumbbell. Each end's label sits beyond that end, away from the other, whatever the axis direction, so a reversed axis never swaps their roles. The formatter's context names the end (`role`). Off by default. **ErrorBarOptions** ```ts interface ErrorBarOptions { lowKey: string; highKey: string; } ``` Error bars of a series (T3): the uncertainty of each mark as two ABSOLUTE bounds read from the host's own columns, on the series' value axis. A symmetric source is the host's arithmetic (`low = v − σ`, `high = v + σ`). - The whisker runs from the low to the high bound through the mark, with a cap at each drawn end, in the chart's neutral foreground ink (not the series colour): uncertainty never reads as another series. It follows its series' visibility and emphasis; it is no pointer or keyboard target of its own. There is no style option. - Both bounds join the automatic value domain. An explicit `min`/`max` still wins: the whisker is then cut at the plot edge without a cap, and the text still states the true bound. A bound a log axis cannot show (at or below 0) is drawn the same way. - The tooltip, the data table and the keyboard announcement read `value (low–high)`; one bound alone is named as the lower or upper bound. CSV and copy-as-table carry the raw bound columns after the value. The legend is unchanged. - A missing or non-finite bound draws the other side only; a low bound above the high bound draws no whisker (development diagnostic); a row without a value draws none. - A series with error bars keeps every row: it is not reduced and it blocks time grouping (development diagnostic), because the bounds of an aggregate are not an aggregate of the bounds. **HighlightStyleOptions** ```ts interface HighlightStyleOptions { dimOpacity?: number; brightness?: number; } ``` Visual styling overrides for hover highlight states. - `dimOpacity` is the opacity this series steps back to while another item is addressed: it replaces the far context step for this series. Default: the far context step (0.64 light, 0.70 dark). - `brightness` is reserved for future use (active-series brightness boost). **HistogramAmountOptions** ```ts type HistogramAmountOptions = | { aggregation?: 'count' | 'sum'; areaProportional?: boolean; } | { aggregation: 'mean'; areaProportional?: false; }; ``` What a bin's height is (T9). By default its amount: the count, or the sum or mean of `yKey`. `areaProportional: true` draws, for a count or a sum, the amount per narrowest bin width (amount × narrowest width / bin width), so a bar's AREA is proportional to its amount where bins differ in width; equal bins draw exactly the same either way. Labels, the tooltip value and the announcement keep the amount; the tooltip adds the drawn rate "per {narrowest width}". A mean is not additive over a width, so it takes no `areaProportional`. **HistogramBinRuleOptions** ```ts type HistogramBinRuleOptions = | { binCount?: number; binWidth?: never; bins?: never; } | { binCount?: never; binWidth: number; bins?: never; } | { binCount?: never; binWidth?: never; bins: [number, number][]; }; ``` The one bin rule of a histogram (T9): a target `binCount` (default 10, round boundaries), a `binWidth` in x units (every bin that wide, on multiples of it; at most 1 000 bins, else the default applies with a development diagnostic), or explicit consecutive `bins`. Only one may be set; an untyped caller that sets several gets `bins`, then `binWidth`, then `binCount`, with a development diagnostic. Every bin includes its lower bound; the last also its upper bound. **HistogramSeriesOptions** ```ts type HistogramSeriesOptions = HistogramSeriesOptionsBase & HistogramBinRuleOptions & HistogramAmountOptions; ``` **LineSeriesOptions** ```ts interface LineSeriesOptions extends SeriesOptionsBase { type: 'line'; stroke?: string; strokeWidth?: number; strokeOpacity?: number; lineDash?: number[]; marker?: MarkerOptions; connectMissingData?: boolean; curve?: CurveType; label?: PointLabelOptions; errorBars?: ErrorBarOptions; zones?: SeriesZones; } ``` **PieSeriesOptions** ```ts interface PieSeriesOptions { type: 'pie' | 'donut'; valueKey: string; categoryKey?: string; name?: string; id?: string; innerRadius?: number; outerRadius?: number; padAngle?: number; colors?: string[]; stroke?: string; visible?: boolean; showInLegend?: boolean; highlightStyle?: HighlightStyleOptions; animation?: boolean | SeriesAnimationOptions; } ``` **ScatterErrorBarOptions** ```ts interface ScatterErrorBarOptions extends ErrorBarOptions { xLowKey?: string; xHighKey?: string; } ``` Error bars of a scatter series (T3): the value-axis pair of {@link ErrorBarOptions} and, on a numeric x axis, an x pair (both keys or neither), which joins the x domain and the x reading of the tooltip, table and announcement. **ScatterSeriesOptions** ```ts interface ScatterSeriesOptions extends SeriesOptionsBase { type: 'scatter'; sizeKey?: string; sizeRange?: [number, number]; sizeDomain?: readonly [number, number]; sizeName?: string; fill?: string; fillOpacity?: number; stroke?: string; strokeWidth?: number; marker?: Pick; label?: PointLabelOptions; paint?: DatumPaintResolver; errorBars?: ScatterErrorBarOptions; } ``` **SeriesAnimationOptions** ```ts interface SeriesAnimationOptions { enabled?: boolean; entrance?: boolean | SeriesEntranceMotionOptions; exit?: boolean | ExitMotionOptions; } ``` A series' own motion: only what a series owns, its entrance and its exit. Update, tooltip, attention and replay are the chart's. `false` turns both off for this series; reduced motion always wins. **SeriesEntranceMotionOptions** ```ts interface SeriesEntranceMotionOptions { enabled?: boolean; duration?: number; easing?: ChartMotionEasing; type?: AnimationType; delay?: number; } ``` A series' own entrance: the chart's entrance with a delay of its own. **SeriesOptions** ```ts type SeriesOptions = | LineSeriesOptions | AreaSeriesOptions | BarSeriesOptions | HistogramSeriesOptions | ScatterSeriesOptions | import('./candlestick-series-options').CandlestickSeriesOptions | import('./ohlc-series-options').OhlcSeriesOptions | import('./waterfall-series-options').WaterfallSeriesOptions | import('./range-series-options').RangeAreaSeriesOptions | import('./range-series-options').RangeBarSeriesOptions | import('./range-series-options').DumbbellSeriesOptions | import('./range-series-options').LollipopSeriesOptions | import('./box-plot-series-options').BoxPlotSeriesOptions; ``` A series `` renders: the thirteen Cartesian types, each drawn by its registered plug-in. A pie, donut or heatmap is a family of its own (``, ``); its options are not a `` series. **SeriesOptionsBase** ```ts interface SeriesOptionsBase { type: SeriesType; xKey: string; yKey?: string; name?: string; id?: string; valueSemantics?: ChartValueSemantics; visible?: boolean; showInLegend?: boolean; yAxisId?: string; highlightStyle?: HighlightStyleOptions; animation?: boolean | SeriesAnimationOptions; dataGrouping?: SeriesDataGroupingOverride | false; } ``` **SeriesType** ```ts type SeriesType = SeriesOptions['type']; ``` The series types a `` renders: exactly the `type` of every `SeriesOptions` member, each drawn by a series plug-in. A standalone family (pie, heatmap, treemap, …) or a scalar is a component of its own, never a `` series, so it is no `SeriesType`. **StackTotalFormatterContext** ```ts interface StackTotalFormatterContext { readonly datum: ChartDatum; readonly stackGroup?: string; } ``` What a stack total's formatter knows besides the number. **StackTotalOptions** ```ts interface StackTotalOptions extends Pick< LabelOptions, 'enabled' | 'format' | 'fontSize' | 'color' | 'offset' | 'background' > { formatter?: (value: number, context?: StackTotalFormatterContext) => string; } ``` One total label per stack and category: the net sum of the stack's visible members, the number the shared tooltip names as the stack's total. It sits beyond the end of the side its sign points to (above a positive vertical stack, below a negative one), in the one label colour. It has one place: a total that would leave the plot, or collide with another total, is hidden, and its value stays in the tooltip, the data table and the announcement. A percentage stack has no total (it always makes 100 %). Declared on a member of the stack; the first member (in series order) that declares it sets the stack's total. Present means on, unless `enabled: false`.