# Charts

Responsive charts with up to five API series, typed point events, and an accessible data table.

URL: https://webrad.atentor.com/docs/charts
Updated: 2026-11-07

WebCharts · Standard · Visual · 4 events

## Quick start

Add **Charts1** in the Designer. Use the example in a page method.

```ts
Charts1.chartsConfig = {
  ...Charts1.chartsConfig,
  type: 'bar',
  title: 'Monthly sales',
  valuePrefix: '$',
  decimalPlaces: 2,
};
Charts1.data = [{
  id: 'sales', name: 'Sales', color: '#58b9f5',
  points: [{ label: 'January', value: 1200 }, { label: 'February', value: 1800 }],
}];
Charts1.onPointClick = (_sender, event) => {
  Message(event.detail.label + ': ' + event.detail.value);
};
```

Charts observes successful API responses; it does not execute requests. Designer samples are illustrations. Preview uses actual responses or the empty state.

## Configure a chart

1. Add **Charts** from the palette. Double-click it or choose **Configure Charts** in the Inspector.
2. Choose doughnut, pie, bar, horizontal bar, line, area, radar, or polar-area presentation.
3. Set the title, subtitle, legend, grid, labels, stacking, and value formatting.
4. In **Appearance → Fonts & colors**, choose the general/legend fonts, colors, and optional Lucide title icon.
5. Configure up to five series. Each has its own name, color, API Client, endpoint, response list, label field, and numeric value field.
6. Click **Save chart** to persist the configuration. Cancel or Escape discards the draft.

Prepare the endpoint's response schema in API Client first. List and field selectors follow that schema. Paths use JSON Pointer, such as /data for the list and /name or /total for fields relative to one item.

## Load and inspect data

Execute the configured API operation from a page event. Charts observes that response and subsequent successful executions; each series may use a different client or endpoint. It also reads a successful response already available when the binding is attached.

Use data for transient series supplied by code, or chartsConfig for presentation. clear() removes displayed points; an active API binding can populate them again on its next successful response. Runtime assignments do not change the saved project.

Invalid or missing numeric measurements are omitted. Circular charts exclude negative measurements from the drawing and keep them in the data table. Cartesian charts support negative values. Empty responses display the configured empty message.

## Point interaction

Link **OnPointClick** in Interaction. event.detail contains label, value, seriesId, seriesName, and index. The same activation supports mouse, touch, Enter, and Space. selectedLabel, selectedValue, and selectedSeriesId expose the last selection.

The Designer and editor use an identified sample. Preview and exports show actual data or the empty state. The chart and accessible data table resize with the component.

## More examples

Observe an API operation

```ts
// Configure a series bound to ApiClient1 in the chart editor first.
const series = Charts1.chartsConfig.series[0];
if (!series) throw new Error('Configure a chart series first.');
const operation = ApiClient1.operations.find(item => item.id === series.operationId);
if (!operation) throw new Error('Configure the series API operation first.');
const unsubscribe = Charts1.bindApiClient(ApiClient1, operation.id, series.id);
try {
  await ApiClient1.execute(operation.name);
} finally {
  unsubscribe(); // This example observes one execution.
}
// Designer-configured series are bound and released automatically.
```

## Inspector properties

Component options and defaults. Fields without runtime access are configured in the Inspector.

| Property / source | Type and options | Default | Runtime access |
| --- | --- | --- | --- |
| `name` — Name · Identity | `string` | `—` | name |
| `x` — Left · Size & position | `number` | `0` | x |
| `y` — Top · Size & position | `number` | `0` | y |
| `width` — Width · Size & position | `number` | `480` | width |
| `height` — Height · Size & position | `number` | `320` | height |
| `itemWidth` — Responsive width · Responsive size — Fit content grows the item to its widest rendered child and preserves child intrinsic widths; minimum and maximum width remain limits. | `enum` — `fixed` `stretch` `fit-content` | `"fixed"` | Inspector / configuration |
| `itemHeight` — Responsive height · Responsive size — Fit content grows the item to its lowest rendered child and preserves child intrinsic heights; minimum and maximum height remain limits. | `enum` — `fixed` `stretch` `fit-content` | `"fixed"` | Inspector / configuration |
| `itemMinWidth` — Minimum width · Responsive size | `number` | `0` | Inspector / configuration |
| `itemMaxWidth` — Maximum width · Responsive size | `number` | `null` | Inspector / configuration |
| `itemMinHeight` — Minimum height · Responsive size | `number` | `0` | Inspector / configuration |
| `itemMaxHeight` — Maximum height · Responsive size | `number` | `null` | Inspector / configuration |
| `itemGrow` — Grow · Responsive size | `number` | `0` | Inspector / configuration |
| `itemShrink` — Shrink · Responsive size — Allows fixed and stretch flow items to yield space. Fit-content keeps its intrinsic size so its children are not compressed. | `boolean` | `true` | Inspector / configuration |
| `itemAlignSelf` — Item alignment · Responsive size — Cross-axis alignment for this item in a row or column. Auto inherits the parent alignment; responsive cross-axis stretch retains its sizing behavior. | `enum` — `auto` `start` `center` `end` `stretch` | `"auto"` | Inspector / configuration |
| `itemHorizontalAnchor` — Horizontal anchor · Anchors & offsets | `enum` — `start` `center` `end` `stretch` | `"start"` | Inspector / configuration |
| `itemVerticalAnchor` — Vertical anchor · Anchors & offsets | `enum` — `start` `center` `end` `stretch` | `"start"` | Inspector / configuration |
| `itemLeft` — Left inset · Anchors & offsets | `number` | `0` | Inspector / configuration |
| `itemRight` — Right inset · Anchors & offsets | `number` | `0` | Inspector / configuration |
| `itemTop` — Top inset · Anchors & offsets | `number` | `0` | Inspector / configuration |
| `itemBottom` — Bottom inset · Anchors & offsets | `number` | `0` | Inspector / configuration |
| `margin` — Margin · Spacing — Outer spacing on all four sides, in pixels. Row and column layouts include this spacing between components. | `number` | `0` | margin |
| `marginTop` — Margin top · Spacing — Outer spacing on this side, in pixels. Overrides the shared Margin value. | `number` | `0` — Derived from saved properties | marginTop |
| `marginRight` — Margin right · Spacing — Outer spacing on this side, in pixels. Overrides the shared Margin value. | `number` | `0` — Derived from saved properties | marginRight |
| `marginBottom` — Margin bottom · Spacing — Outer spacing on this side, in pixels. Overrides the shared Margin value. | `number` | `0` — Derived from saved properties | marginBottom |
| `marginLeft` — Margin left · Spacing — Outer spacing on this side, in pixels. Overrides the shared Margin value. | `number` | `0` — Derived from saved properties | marginLeft |
| `visible` — Visible · Behavior | `boolean` | `true` | visible |
| `collapseWhenHidden` — Collapse when hidden · Behavior — Removes the component from the layout while it is not visible. | `boolean` | `true` | collapseWhenHidden |
| `enabled` — Enabled · Behavior | `boolean` | `true` | enabled |
| `chartsConfig` — Chart and data series · Charts — Choose a chart, customize its appearance and bind up to five API response series. | `charts-config` — Editor: charts-configurator | `{"schemaVersion":1,"type":"bar","title":"Chart title","subtitle":"","fontFamily":"inherit","legendFontFamily":"inherit","textColor":null,"titleColor":null,"subtitleColor":null,"legendColor":null,"titleIcon":null,"showLegend":true,"legendPosition":"bottom","showGrid":true,"showLabels":false,"smooth":true,"stacked":false,"innerRadius":65,"valuePrefix":"","valueSuffix":"","decimalPlaces":0,"emptyText":"No data to display","series":[]}` | chartsConfig |
| `currentRowBindings` — Current row · Data — Bind writable visual values to fields of this repeated row. | `current-row-bindings` — Editor: current-row-bindings | `[]` | currentRowBindings |

## API in code

| Member | Signature | Access |
| --- | --- | --- |
| `chartsConfig` — Persisted chart appearance and up to five declarative API series. | `get chartsConfig(): WebChartsConfiguration;` | Read and write |
| `data` — Current transient series. Values remain numeric and never enter the Project Model. | `get data(): readonly WebChartSeriesData[];` | Read and write |
| `selectedLabel` | `get selectedLabel(): string \| null;` | Read-only |
| `selectedValue` | `get selectedValue(): number \| null;` | Read-only |
| `selectedSeriesId` | `get selectedSeriesId(): string \| null;` | Read-only |
| `onPointClick` | `set onPointClick(handler: WebChartPointEventHandler<this> \| null);` | Read and write |

### `clear`

method

```ts
clear(): void;
```

Clears displayed points; an existing binding can refresh after the next successful request.

Example

```ts
Charts1.clear();
```

### `bindApiClient`

method

```ts
bindApiClient(apiClient: WebApiClient, operationId: string, seriesId: string): () => void;
```

Binds one configured series to a named API operation by stable operation ID.
Reads existing successful data and subsequent results; never executes a request.

Example

```ts
const series = Charts1.chartsConfig.series[0];
if (!series) throw new Error('Configure a series bound to ApiClient1 first.');
const unsubscribe = Charts1.bindApiClient(ApiClient1, series.operationId, series.id);
// Release a handwritten binding when it is no longer needed.
unsubscribe();
```

### `dispose`

method

```ts
dispose(): void;
```

Example

```ts
// Call only when disposing of an instance whose lifecycle you control.
Charts1.dispose();
```

Inherited members (26)

| Member | Signature | Access |
| --- | --- | --- |
| `currentRowBindings` | `currentRowBindings: readonly WebCurrentRowBinding[];` | Read and write |
| `element` | `readonly element: TElement;` | Read-only |
| `id` | `readonly id: string;` | Read-only |
| `name` | `readonly name: string;` | Read-only |
| `visible` | `visible: boolean;` | Read and write |
| `collapseWhenHidden` | `collapseWhenHidden: boolean;` | Read and write |
| `enabled` | `enabled: boolean;` | Read and write |
| `x` | `x: number;` | Read and write |
| `y` | `y: number;` | Read and write |
| `width` | `width: number;` | Read and write |
| `height` | `height: number;` | Read and write |
| `margin` — Outer spacing on all four sides, in pixels. | `margin: number;` | Read and write |
| `marginTop` | `marginTop: number;` | Read and write |
| `marginRight` | `marginRight: number;` | Read and write |
| `marginBottom` | `marginBottom: number;` | Read and write |
| `marginLeft` | `marginLeft: number;` | Read and write |
| `alignSelf` | `alignSelf: RuntimeLayoutAlignSelf;` | Read and write |
| `tabIndex` | `tabIndex: number;` | Read and write |
| `backgroundColor` | `backgroundColor: string;` | Read and write |
| `color` | `color: string;` | Read and write |
| `borderColor` | `borderColor: string;` | Read and write |

### `focus`

method

```ts
focus(options?: FocusOptions): void;
```

### `show`

method

```ts
show(): void;
```

### `hide`

method

```ts
hide(): void;
```

### `bindEvent`

method

```ts
bindEvent(eventName: string, handler: WebComponentEventHandler<this> | null): () => void;
```

### `emit`

method

```ts
emit(eventName: string, detail?: unknown): boolean;
```

## Events

Link methods in **Interaction**. [How to use events](https://webrad.atentor.com/docs/interactions).

### OnPointClick

[WebChartPointEventDetail](https://webrad.atentor.com/docs/types#webchartpointeventdetail) in `event.detail` · `label`, `value`, `seriesId`, `seriesName`, `index`

Runs when a chart point is clicked or activated with the keyboard.

Signature and example

```ts
import type { WebCharts, WebChartPointEventDetail } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Charts1PointClick(
    sender: WebCharts,
    event: CustomEvent<WebChartPointEventDetail>,
  ): Promise<void> {
    console.log(event.detail);
    const { label, value, seriesId, seriesName, index } = event.detail;
    console.log(label, value, seriesId, seriesName, index);
  }
}
```

### OnClick

Standard event (Event).

Signature and example

```ts
import type { WebCharts } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Charts1Click(
    sender: WebCharts,
    event: Event,
  ): Promise<void> {
    console.log(sender.name, event.type);
  }
}
```

### OnMouseEnter

Standard event (Event).

Signature and example

```ts
import type { WebCharts } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Charts1MouseEnter(
    sender: WebCharts,
    event: Event,
  ): Promise<void> {
    console.log(sender.name, event.type);
  }
}
```

### OnMouseLeave

Standard event (Event).

Signature and example

```ts
import type { WebCharts } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Charts1MouseLeave(
    sender: WebCharts,
    event: Event,
  ): Promise<void> {
    console.log(sender.name, event.type);
  }
}
```