# [Usage](../../../usage.md) > [Components](../basics.md) > [Visuals](../basics.md) > Charts

Simple HTML interactive charts for your blade template, without using external/additional libraries. Use them for dashboards and reports where a lightweight native chart suffices; reach for a full JS library only for highly custom interactions, and use [FastCard](fastcard.md) when you need a single KPI number instead of a series.

![image](img/chart_1.png)

```php
{!!
  \KFramework\Components\Visual\Chart::make('Chart label')
    ->setType('vbar')
    ->setDimension(300)
    ->setSchema([
        [
            'name' => 'first',
            'value' => 10,
            'color' => 'blue'
        ],
        [
            'name' => 'second',
            'value' => 0,
            'color' => 'green'
        ],
        [
            'name' => 'third',
            'value' => -10,
            'color' => 'yellow'
        ]
    ])
!!}
```

**End-to-end example:** monthly revenue bar chart from aggregated data.
```php
// Blade:
{!!
  \KFramework\Components\Visual\Chart::make('Revenue')
    ->setType('vbar')
    ->setDimension(300)
    ->setSchema([
        ['name' => 'Jan', 'value' => 1200, 'color' => 'blue'],
        ['name' => 'Feb', 'value' => 1800, 'color' => 'green'],
    ])
!!}

// Controller:
use KFramework\Components\Visual\Chart;

$chart = Chart::make('Revenue')
    ->setType('vbar')
    ->setDimension(300)
    ->setSchema([
        ['name' => 'Jan', 'value' => 1200, 'color' => 'blue'],
        ['name' => 'Feb', 'value' => 1800, 'color' => 'green'],
    ]);

return view('reports.revenue', compact('chart'));
```

---
## Usage

- Blade:
```php
{!! \KFramework\Components\Visual\Chart::make() !!}
```
- Controller:
```php
Chart::make()
```

---
## Standard attributes

- `uuid`
- `id`
- `classes`
- `extraAttributes`
- `name` | `label`
  -  Setting the name will set the label of the chart, `name` overrides `label`.
- `schema` — dataset list (`name`/`value`/`color`) as documented in "How to write schemas and datasets" below.
- `type`
  - Set type of the chart between:
    - `progress_bar`: simple progress bar from 0 to 100%
    - `progress_circle`: simple progress bar circled from 0 to 100%
    - `vbar`: vertical bar chart
    - `hbar`: horizontal bar chart
    - `vstack`: vertical stacked bar chart, same schema as `vbar`
    - `hstack`: horizontal stacked bar chart, same schema as `hbar`
    - `vcomposite`: vertical composite bar chart, same schema and rendering as `vstack` with a component-based legend
    - `hcomposite`: horizontal composite bar chart, same schema and rendering as `hstack` with a component-based legend
    - `funnel`: funnel chart for ordered stages, same schema as `vbar`
    - `pie`: pie chart
    - `doughnut`: doughnut chart
    - `gauge`: gauge chart
    - `hspline`: hard lines spline chart
    - `sspline`: soft lines spline chart
    - `area`: soft spline chart with filled area, same schema as `sspline`
    - `scatter`: scatter plot without connecting lines, same schema as `sspline`
    - `radar`: radar chart for multi-dimension profiles, one polygon per dataset
    - `heatmap`: heatmap grid from labeled rows of cells
    - `waterfall`: waterfall chart from ordered deltas with optional totals
    - `gantt`: gantt chart

String types match the values of the `KFramework\Enums\ChartType` enum.
- `columnSpan`
- `dimension`
  - Used to regulate the height of the chart, has no effect on `gantt` type. Use `type` to switch chart kind; `dimension` only affects height except for `gantt`.
- `small` | `->setSmall()`
  - For `gauge` charts renders a compact variant without chrome: hides the chart title, the chart area border, the gauge ticks, the gauge legend and the pie slice labels. The chart uses `0` padding and `0` margin. Other chart types ignore this preset for layout.

See their usage and description [here](../basics.md).

---
## Component-specific attributes

`displayLegend` | `->setDisplayLegend()`  

Enable or disable legend below the chart.

| Types  | Default |
|--------|---------|
| `bool` | `true`  |


`horizontalValuesOrientation` | `->setHorizontalValuesOrientation()`

Change the orientation of the text of X axis values, useful for small charts to not overlap the values.  
Can be:
- `horizontal` (default)
- `vertical`

| Types    | Default      |
|----------|--------------|
| `string` | `horizontal` |

---
## Localization

Built-in chart labels (empty states, doughnut totals, gauge scale, Gantt markers and fallback axis names) follow the application locale through the `kfw::visual` language files. Dataset names, values and explicit labels are always rendered verbatim.

---
## How to write schemas and datasets

There are two charts that simply represent progress from 0 to 100: `progress_bar` and `progress_circle`. These two types of graph does not handle a dataset or a schema but a simply `value` (`->setValue()`) from `0` to `100` (integer).

The other charts can work with a single dataset or multiple datasets.

The `vbar`, `hbar`, `pie` and `doughnut` charts uses basic schema:

```php
->setSchema([
    // Each array is a single dataset
    [
        'name' => // required: the name of the series
        'value' => // required: numeric value (int, float, double, etc.)
        'color' => // optional: set the background color for the dataset, is an HTML color
        'label' => // optional: alternative label for the value to place in the popup and in the graph, the dimension will still be regulated by the value itself
    ],
])
```

example above:

```php
->setSchema([
    [
        'name' => 'first',
        'value' => 10,
        'color' => 'blue'
    ],
    [
        'name' => 'second',
        'value' => 0,
        'color' => 'green'
    ],
    [
        'name' => 'third',
        'value' => -10,
        'color' => 'yellow'
    ]
])
```

And it can also handle sub-datasets:

```php
->setSchema([
    [
        'name' => 'first',
        'value' => [
            [
                'name' => 'first subdataset',
                'value' => 1,
                'color' => 'lightblue'
            ],
            [
                'name' => 'second subdataset',
                'value' => 5,
                'color' => 'lightgreen'
            ],
            [
                'name' => 'third subdataset',
                'value' => 3,
                'color' => 'orange'
            ]
        ],
    ],
    [
        'name' => 'second',
        'value' => 0,
        'color' => 'green'
    ],
    [
        'name' => 'third',
        'value' => -10,
        'color' => 'yellow'
    ]
])
```

Result example in a vertical bar chart:

![image](img/chart_2.png)

Possible `value` for bar, stacked, funnel, pie and doughnut charts:
- `numbers`
- `subdatasets`

For the `gauge` graph, the schema will be similar to the `doughnut` chart, except, the `max` value is defined:

```php
->setSchema([
    [
        'name' => 'first',
        'value' => 10,
        'color' => 'blue'
    ],
    [
        'name' => 'second',
        'value' => 3,
        'color' => 'green'
    ],
    // other datasets
    'max' => 20
])
```

_NOTE_: the `max` parameter is not required for the gauge chart, but without using it you will never see the grayed out region, just a half doughnut chart.

For `hspline`, `sspline`, `area` and `scatter` graph type the schema structure will change a bit, like the above but with required sub-datasets:

```php
->setSchema([
    // Each array is a single dataset
    [
        'name' => 'first',
        'value' => [
            [
                'x' => 1,
                'y' => 7,
                'label' => // optional, label for the point
            ],
            [
                'x' => 5,
                'y' => 3,
                'label' => // optional, label for the point
            ],
            [
                'x' => 9,
                'y' => 5,
                'label' => // optional, label for the point
            ],
        ],
        'color' => // optional: set the background color for the dataset, is an HTML color
    ],
])
```

Possible `x` and `y` for spline charts:
- `numbers`  
(dates)
- `hh:ii`
- `yyyy-mm-dd`
- `yyyy-mm-dd hh:ii`

For the `radar` type, each dataset is a named series rendered as a polygon over shared axes:

```php
->setSchema([
    // Each array is a single series
    [
        'name' => 'first series',
        'value' => [
            [
                'axis' => 'Speed',
                'value' => 8,
                'label' => // optional, label for the vertex
            ],
            [
                'axis' => 'Power',
                'value' => 6,
            ],
        ],
        'color' => // optional: set the color for the series, is an HTML color
    ],
])
```

At least three distinct axes are required. Missing axis values default to the scale minimum.

For the `heatmap` type, each dataset is a labeled row of cells. Cell intensity is scaled between the minimum and maximum values:

```php
->setSchema([
    // Each array is a single row
    [
        'name' => 'Monday',
        'value' => [
            [
                'name' => 'Morning',
                'value' => 3,
                'label' => // optional, label shown inside the cell
                'color' => // optional: overrides the computed intensity color
            ],
        ],
    ],
])
```

For the `waterfall` type, entries are ordered steps rendered as floating columns. Entries flagged with `total` render from the zero baseline to the stated `value` when present, otherwise to the running total:

```php
->setSchema([
    ['name' => 'Start', 'value' => 100, 'total' => true],
    ['name' => 'Sales', 'value' => 40],
    ['name' => 'Refunds', 'value' => -15],
    ['name' => 'End', 'total' => true],
])
```

Rising steps default to the success color, falling steps to the danger color and totals to the primary color; an explicit `color` overrides the default.

For the `gantt` type of graph, there is no definable height as the other graphs type: that's because the height is defined by the datasets themselves.
The new schema for the Gantt type will be like:

```php
->setSchema([
    // Each array is a single dataset
    [
        'name' => 'first',
        'start' => 1
        'end' => 2
        'nested' => // optional: inner datasets, same structure
        'color' => // optional: set the background color for the dataset, is an HTML color
    ],
])
```

Example of nested dataset:

```php
->setSchema([
    [
        'name' => 'First Task',
        'start' => '2025-12-01',
        'end' => '2025-12-02',
        'color' => 'orange',
        'nested' => [
            [
                'name' => 'Subtask 1',
                'start' => '2025-12-01',
                'end' => '2025-12-01 12:00',
                'color' => 'blue',
            ],
            [
                'name' => 'Subtask 2',
                'start' => '2025-12-01 12:00',
                'end' => '2025-12-02',
                'color' => 'red',
            ],
        ],
    ],
    [
        'name' => 'Second Task',
        'start' => '2025-12-01 14:00',
        'end' => '2025-12-03',
        'color' => 'lightblue',
    ],
])
```

---
## Chart types

### `progress_bar` and `progress_circle` | Progress bar or circled progress

![image](img/chart_12.png)

### `vbar` | Vertical bar chart

![image](img/chart_1.png)


### `hbar` | Vertical bar chart

![image](img/chart_3.png)


### `vstack` | Vertical stacked bar chart

Same schema as `vbar`. Segments within each category are stacked on a shared baseline, which suits part-to-whole comparisons across categories.

### `hstack` | Horizontal stacked bar chart

Same schema as `hbar`. Segments within each row are stacked along a shared baseline, which suits part-to-whole comparisons across rows.

### `vcomposite` | Vertical composite bar chart

Same schema and rendering as `vstack`. Subdatasets are parts of the category total, and the legend lists each distinct component once, which suits composition analysis across categories.

### `hcomposite` | Horizontal composite bar chart

Same schema and rendering as `hstack`. Subdatasets are parts of the row total, and the legend lists each distinct component once, which suits composition analysis across rows.

### `funnel` | Funnel chart

Same schema as `vbar`. Stages are rendered in schema order with decreasing widths, and the step-to-step conversion rate is shown next to each stage.

### `pie` | Pie chart

![image](img/chart_4.png)

Pie chart with subdatasets:

![image](img/chart_5.png)

### `doughnut` | Doughnut chart

![image](img/chart_6.png)

Doughnut chart with subdatasets:

![image](img/chart_7.png)

### `gauge` | Gauge chart

![image](img/chart_11.png)

Compact gauge with `->setSmall(true)`:

```php
{!!
  \KFramework\Components\Visual\Chart::make('Load')
    ->setType('gauge')
    ->setSmall(true)
    ->setDimension(200)
    ->setSchema([
        ['name' => 'used', 'value' => 70, 'color' => 'blue'],
        'max' => 100,
    ])
!!}
```

A small gauge hides the chart title, the chart area border, the gauge ticks, the gauge legend and the pie slice labels. The chart container and wrapper render with `0` padding and `0` margin. The central gauge value and maximum remain visible. The wrapper does not force the full `dimension` height and the SVG scales with `height: auto` in a `2 / 1` aspect ratio, so no empty vertical space is reserved.

### `hspline` | Hard Spline chart

![image](img/chart_8.png)

### `sspline` | Soft Spline chart

![image](img/chart_9.png)

### `area` | Area chart

Same schema as `sspline`. The region below the soft line is filled, which suits volume and accumulation trends.

### `scatter` | Scatter chart

Same schema as `sspline`. Points are rendered without connecting lines, which suits correlation and distribution analysis.

### `radar` | Radar chart

Multi-dimension profiles with one polygon per dataset, which suits comparison across shared axes.

### `heatmap` | Heatmap chart

Labeled rows of intensity-scaled cells with a minimum-to-maximum scale, which suits activity and density analysis.

### `waterfall` | Waterfall chart

Ordered deltas rendered as floating columns with optional totals, which suits bridge analysis from a starting value to an ending value.

### `gantt` | Gantt chart

![image](img/chart_10.png)

## See also
- [Components basics](../basics.md)
- [FastCard](fastcard.md), [Card](card.md), [Table](table.md)
- [schema](../shared_attributes/schema.md), [type](../shared_attributes/type.md), [dimension](../shared_attributes/dimension.md), [small](../shared_attributes/small.md)