# Islands (/islands/overview)





An **island** is a reusable, typed visual block. You don't write rendering code. You declare
an island in the manifest, bind it to fields that exist in your data, and the runtime renders
it. The same renderers the runtime ships power the live previews below:
each tile is a real OpenIslands island, not a screenshot.

## A metric, live [#a-metric-live]

A `metric.kpi` reads the last row of its dataset for the value, the row before it for the
delta, and draws a sparkline over the time axis it finds.

<LiveIsland type="metric.kpi" config="{ title: &#x22;Net worth&#x22;, value: &#x22;net_worth_eur&#x22;, compareTo: &#x22;prev&#x22;, format: &#x22;eur&#x22; }" data="netWorthByMonth" />

```jsonc title="manifest.json"
{
  "type": "metric.kpi",
  "title": "Net worth",
  "dataset": "net_worth",
  "value": "net_worth_eur",
  "compareTo": "prev",
  "format": "eur"
}
```

## A note, live [#a-note-live]

A `note.card` renders Markdown and binds to no data, handy for context, captions, and links
right inside a dashboard.

<LiveIsland type="note.card" config="{ markdown: &#x22;## Hello\nLive island.&#x22; }" height="120" />

## The island registry [#the-island-registry]

Every built-in island and the fields it requires. Pick the built-in that fits before
reaching for a custom renderer.

Each type links to its section with a live preview and full configuration.

| Type                                                              | Required fields                          | What it is                                                                                                 |
| ----------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| [`metric.kpi`](/islands/metrics-and-gauges.md#metrickpi)             | `dataset`, `value`                       | A single number off the last row, with an optional delta and sparkline.                                    |
| [`metric.scorecard`](/islands/metrics-and-gauges.md#metricscorecard) | `dataset`, `stats`                       | A compact scorecard of several KPIs off the last row.                                                      |
| [`gauge.rings`](/islands/metrics-and-gauges.md#gaugerings)           | `dataset`, `rings`                       | Concentric goal rings off the last row.                                                                    |
| [`gauge.goal`](/islands/metrics-and-gauges.md#gaugegoal)             | `dataset`, `goals`                       | One ring per goal, each measured against a goal or band.                                                   |
| [`gauge.meter`](/islands/metrics-and-gauges.md#gaugemeter)           | `dataset`, `meters`                      | Horizontal usage bars off the last row.                                                                    |
| [`status.grid`](/islands/metrics-and-gauges.md#statusgrid)           | `dataset`, `label`, `state`              | A responsive grid of service/check status tiles.                                                           |
| [`timeseries.line`](/islands/charts.md#timeseriesline)               | `dataset`, `x`, `y`                      | A line chart over time; `y` may be one field or many.                                                      |
| [`category.bar`](/islands/charts.md#categorybar)                     | `dataset`, `x`, `y`                      | A bar chart, optionally grouped or stacked.                                                                |
| [`category.combo`](/islands/charts.md#categorycombo)                 | `dataset`, `x`, `bars`, `lines`          | Bars on a primary axis and lines on a secondary one.                                                       |
| [`waterfall.bars`](/islands/charts.md#waterfallbars)                 | `dataset`, `label`, `value`              | A waterfall of signed steps to a running total.                                                            |
| [`divergence.bars`](/islands/charts.md#divergencebars)               | `dataset`, `x`, `value`                  | Signed bars diverging up/down from a zero baseline, colored by value band.                                 |
| [`rank.list`](/islands/charts.md#ranklist)                           | `dataset`, `label`, `value`              | A ranked Top-N list with proportional bars.                                                                |
| [`breakdown.treemap`](/islands/charts.md#breakdowntreemap)           | `dataset`, `label`, `value`              | A treemap of parts of a whole.                                                                             |
| [`category.pie`](/islands/charts.md#categorypie)                     | `dataset`, `label`, `value`              | A pie or donut of one series' share across a few categories.                                               |
| [`correlation.scatter`](/islands/charts.md#correlationscatter)       | `dataset`, `x`, `y`                      | A scatter or bubble plot of two numeric fields.                                                            |
| [`distribution.heatmap`](/islands/charts.md#distributionheatmap)     | `dataset`, `x`, `y`, `value`             | A matrix heatmap of a value across two category axes.                                                      |
| [`activity.calendar`](/islands/charts.md#activitycalendar)           | `dataset`, `date`, `value`               | A GitHub-style calendar heatmap of a daily value.                                                          |
| [`funnel.steps`](/islands/charts.md#funnelsteps)                     | `dataset`, `label`, `value`              | A conversion funnel of sequential stages.                                                                  |
| [`compare.radar`](/islands/charts.md#compareradar)                   | `dataset`, `metrics`                     | A radar chart comparing rows across several metrics.                                                       |
| [`map.choropleth`](/islands/charts.md#mapchoropleth)                 | `dataset`, `region`, `value`             | A geographic choropleth shading regions by a value.                                                        |
| [`table.grid`](/islands/tables-and-feeds.md#tablegrid)               | `dataset`                                | A data table with optional details, grouping, and drilldown.                                               |
| [`timeline.feed`](/islands/tables-and-feeds.md#timelinefeed)         | `dataset`, `ts`, `titleField`            | A chronological feed of rows, plain or rich.                                                               |
| [`search.box`](/islands/tables-and-feeds.md#searchbox)               | `dataset`, `fields`, `titleField`        | A client-side search over a dataset.                                                                       |
| [`note.card`](/islands/content-and-layout.md#notecard)               | `markdown`                               | Markdown content; no data.                                                                                 |
| [`source.doc`](/islands/content-and-layout.md#sourcedoc)             | (none)                                   | An embedded document or link (`file` or `href`).                                                           |
| [`content.editor`](/islands/content-and-layout.md#contenteditor)     | (none)                                   | A full-page workspace to browse and edit markdown files (`file` or `dir`); no data.                        |
| [`layout.row`](/islands/content-and-layout.md#layoutrow)             | `islands`                                | A full-width structural row holding other islands.                                                         |
| [`form.entry`](/islands/content-and-layout.md#formentry)             | `action`                                 | A data-entry form bound to an action; one typed input per field inserts a row. No data binding of its own. |
| [`board.kanban`](/islands/content-and-layout.md#boardkanban)         | `dataset`, `key`, `column`, `titleField` | A full-bleed kanban board; drag/select moves persist via an update action.                                 |

One layout construct isn't in the table because it isn't an island: a page can split into tabbed
[`groups`](/islands/content-and-layout.md#tabs-groups). Groups are page structure, not a tile, so
they won't appear in `oi.app().listIslands()` either — see [Pages and groups](/concepts/manifest.md#pages-and-groups).

Browse the per-category pages for the full picture: [Metrics & Gauges](/islands/metrics-and-gauges.md),
[Charts](/islands/charts.md), [Tables & Feeds](/islands/tables-and-feeds.md),
[Content & Layout](/islands/content-and-layout.md), and [Custom Islands](/islands/custom.md).


---

*This is one page of the OpenIslands docs. Every page in one file: [/llms-full.txt](/llms-full.txt). Page index: [/llms.txt](/llms.txt). Links above point to `.md` siblings — append `.md` to any page URL for its raw markdown.*