Scripting
Getting Started
Documentation
Changelog
Privacy
Getting Started
Documentation
Changelog
Privacy

RuleLineForLabelChart

RuleLineForLabelChart overlays vertical or horizontal reference lines based on label (or date) positions in a chart. It is commonly used to highlight specific categories or time points in combination with other chart types, such as BarChart or LineChart.

Declaration

1declare const RuleLineForLabelChart: FunctionComponent<{
2  /**
3   * If specified as true, the chart will display labels on the Y-axis, causing rule lines to be drawn horizontally. Defaults to false (vertical lines).
4   */
5  labelOnYAxis?: boolean;
6
7  /**
8   * An array of rule marks, each specifying the label or date to draw a reference line at.
9   */
10  marks: Array<{
11    /**
12     * The label (string or Date) where the rule line should be placed.
13     */
14    label: string | Date;
15
16    /**
17     * Optional calendar component (e.g., 'month', 'day') if using a Date label.
18     */
19    unit?: CalendarComponent;
20  } & ChartMarkProps>;
21}>;

Properties

Property Type Description
labelOnYAxis boolean If true, rule lines are drawn horizontally using Y-axis label positions. Default is vertical.
marks Array An array of labeled rule definitions. Each mark can include styling options from ChartMarkProps.

Each item in marks can include:

  • label: The string or date at which to draw the rule.
  • unit: Optional, only relevant for date-based axes.
  • foregroundStyle: Optional. Controls the color.
  • opacity: Optional. Controls line transparency.
  • lineStyle: Optional. Allows custom dashing (e.g., [3, 2]).

Example: Marking Categories in a Bar Chart

1import {
2  Chart,
3  RuleLineForLabelChart,
4  BarChart,
5  Navigation,
6  NavigationStack,
7  Script,
8  VStack
9} from "scripting"
10
11const data = [
12  { label: "Q1", value: 1500 },
13  { label: "Q2", value: 2300 },
14  { label: "Q3", value: 1800 },
15  { label: "Q4", value: 2700 },
16]
17
18const referenceLines = [
19  { label: "Q2", foregroundStyle: "blue", lineStyle: { dash: [3, 2] } },
20  { label: "Q4", foregroundStyle: "red", opacity: 0.5 },
21]
22
23function Example() {
24  return (
25    <NavigationStack>
26      <VStack
27        navigationTitle="BarChart with Reference Lines"
28        navigationBarTitleDisplayMode="inline"
29      >
30        <Chart frame={{ height: 300 }}>
31          <BarChart marks={data} />
32          <RuleLineForLabelChart marks={referenceLines} />
33        </Chart>
34      </VStack>
35    </NavigationStack>
36  )
37}
38
39async function run() {
40  await Navigation.present({ element: <Example /> })
41  Script.exit()
42}
43
44run()

Use Cases

  • Highlight important events or milestones in a timeline.
  • Visually separate regions in a categorical chart.
  • Indicate thresholds or labels of significance.
Outline