Skip to main content

Component YAML

Defines a reusable dashboard component that can be embedded in canvas dashboards

Properties​

type​

[string] - Refers to the resource type and must be component (required)

display_name​

[string] - Refers to the display name for the component

description​

[string] - Detailed description of the component's purpose and functionality

params​

[array of object] - List of typed parameters that canvases can bind values to when referencing this component. Bound values are available in the renderer properties' templating as {{ .params.<name> }}, and the metrics view metadata of a field-typed param as {{ .fields.<name>.display_name }}, {{ .fields.<name>.format_d3 }}, {{ .fields.<name>.format_preset }} and {{ .fields.<name>.format_type }}.

  • name - [string] - Param name. Must be a valid identifier; referenced in the renderer properties' templating as {{ .params.<name> }}. (required)

  • type - [string] - Param type. Params of type metrics_view must be named metrics_view or end with _metrics_view. (required)

  • description - [string] - Human-facing description of the param

  • required - [boolean] - If true, a canvas item referencing this component must bind a value for the param. Mutually exclusive with default.

  • default - [string, number, boolean] - Default value used when the param is not bound

  • metrics_view - [string] - For measure, dimension and time_dimension params, the name of a sibling param of type metrics_view whose bound metrics view the field must belong to. May be omitted when exactly one metrics_view param is declared.

  • options - [array] - For scalar params, the allowed values. Renders as a select input in visual editors.

input​

[array of object] - List of input variables that can be passed to the component

  • name - [string] - Unique identifier for the variable (required)

  • type - [string] - Data type of the variable (e.g., string, number, boolean) (required)

  • value - [string, number, boolean, object, array] - Default value for the variable. Can be any valid JSON value type

output​

[object] - Output variable that the component produces

  • name - [string] - Unique identifier for the variable (required)

  • type - [string] - Data type of the variable (e.g., string, number, boolean) (required)

  • value - [string, number, boolean, object, array] - Default value for the variable. Can be any valid JSON value type

line_chart​

[object] - (no description)

  • config - [object] - (no description) (required)

    • metrics_view - [string] - Reference to the metrics view to use (required)

    • x - [object] - (no description)

      • field - [string] - Field name from the metrics view (required)

      • title - [string] - Display title for the field

      • format - [string] - Format string for the field

      • type - [string] - Data type of the field (required)

      • timeUnit - [string] - Time unit for temporal fields

    • y - [object] - (no description)

      • field - [string] - Field name from the metrics view (required)

      • title - [string] - Display title for the field

      • format - [string] - Format string for the field

      • type - [string] - Data type of the field (required)

      • timeUnit - [string] - Time unit for temporal fields

    • color - [oneOf] - (no description)

      • option 1 - [object] - (no description)

        • field - [string] - Field name from the metrics view (required)

        • title - [string] - Display title for the field

        • format - [string] - Format string for the field

        • type - [string] - Data type of the field (required)

        • timeUnit - [string] - Time unit for temporal fields

      • option 2 - [string] - (no description)

    • tooltip - [object] - (no description)

      • field - [string] - Field name from the metrics view (required)

      • title - [string] - Display title for the field

      • format - [string] - Format string for the field

      • type - [string] - Data type of the field (required)

      • timeUnit - [string] - Time unit for temporal fields

  • title - [string] - Chart title

  • description - [string] - Chart description

bar_chart​

[object] - (no description)

  • config - [object] - (no description) (required)

    • metrics_view - [string] - Reference to the metrics view to use (required)

    • x - [object] - (no description)

      • field - [string] - Field name from the metrics view (required)

      • title - [string] - Display title for the field

      • format - [string] - Format string for the field

      • type - [string] - Data type of the field (required)

      • timeUnit - [string] - Time unit for temporal fields

    • y - [object] - (no description)

      • field - [string] - Field name from the metrics view (required)

      • title - [string] - Display title for the field

      • format - [string] - Format string for the field

      • type - [string] - Data type of the field (required)

      • timeUnit - [string] - Time unit for temporal fields

    • color - [oneOf] - (no description)

      • option 1 - [object] - (no description)

        • field - [string] - Field name from the metrics view (required)

        • title - [string] - Display title for the field

        • format - [string] - Format string for the field

        • type - [string] - Data type of the field (required)

        • timeUnit - [string] - Time unit for temporal fields

      • option 2 - [string] - (no description)

    • tooltip - [object] - (no description)

      • field - [string] - Field name from the metrics view (required)

      • title - [string] - Display title for the field

      • format - [string] - Format string for the field

      • type - [string] - Data type of the field (required)

      • timeUnit - [string] - Time unit for temporal fields

  • title - [string] - Chart title

  • description - [string] - Chart description

stacked_bar​

[object] - (no description)

  • config - [object] - (no description) (required)

    • metrics_view - [string] - Reference to the metrics view to use (required)

    • x - [object] - (no description)

      • field - [string] - Field name from the metrics view (required)

      • title - [string] - Display title for the field

      • format - [string] - Format string for the field

      • type - [string] - Data type of the field (required)

      • timeUnit - [string] - Time unit for temporal fields

    • y - [object] - (no description)

      • field - [string] - Field name from the metrics view (required)

      • title - [string] - Display title for the field

      • format - [string] - Format string for the field

      • type - [string] - Data type of the field (required)

      • timeUnit - [string] - Time unit for temporal fields

    • color - [oneOf] - (no description)

      • option 1 - [object] - (no description)

        • field - [string] - Field name from the metrics view (required)

        • title - [string] - Display title for the field

        • format - [string] - Format string for the field

        • type - [string] - Data type of the field (required)

        • timeUnit - [string] - Time unit for temporal fields

      • option 2 - [string] - (no description)

    • tooltip - [object] - (no description)

      • field - [string] - Field name from the metrics view (required)

      • title - [string] - Display title for the field

      • format - [string] - Format string for the field

      • type - [string] - Data type of the field (required)

      • timeUnit - [string] - Time unit for temporal fields

  • title - [string] - Chart title

  • description - [string] - Chart description

stacked_bar_normalized​

[object] - Bar chart normalized to 100% values

area_chart​

[object] - Line chart with area

combo_chart​

[object] - Dual-axis chart that draws one measure as bars and another as a line

donut_chart​

[object] - Donut chart

pie_chart​

[object] - Pie chart

scatter_plot​

[object] - Scatter plot

funnel_chart​

[object] - Funnel chart

heatmap​

[object] - Heat map chart to visualize distribution of data

kpi​

[object] - (no description)

  • metrics_view - [string] - Reference to the metrics view to use (required)

  • measure - [string] - Measure to display (required)

  • time_range - [string] - Time range for the KPI (required)

  • comparison_range - [string] - Comparison time range

  • filter - [string] - Filter expression

  • title - [string] - KPI title

  • description - [string] - KPI description

kpi_grid​

[object] - Grid of KPIs

table​

[object] - (no description)

  • metrics_view - [string] - Reference to the metrics view to use (required)

  • columns - [array of oneOf] - Ordered columns of a table, dimensions and measures alike. Each entry is a field name or an object with the name and per-column overrides.

    • option 1 - [string] - Name of the dimension, measure, adhoc measure, or encoded time column (for example ts_rill_TIME_GRAIN_DAY)

    • option 2 - [object] - (no description)

      • name - [string] - Name of the dimension, measure, adhoc measure, or encoded time column (required)

      • width - [integer] - Column width in pixels. Measures and adhoc measures accept 60–300, dimensions and time columns 100–600. The column keeps this width under stretch and fit_to_width. Not allowed on col_dimensions, nor on row dimensions after the first.

      • wrap - [boolean] - Wrap the cell text over wrap_lines lines instead of truncating it; overrides the component-level wrap. Only on a table's dimension columns and on the first row dimension of a pivot.

      • align - [string] - Text alignment of the header and cells, for table columns and measures. Defaults to right for measures and left for dimensions. Not allowed on row_dimensions or col_dimensions.

      • label - [string] - Header text, replacing the display name from the metrics view.

      • format_preset - [string] - Number format preset for a measure in this component only. Mutually exclusive with format_d3.

      • format_d3 - [string] - d3 format string for a measure in this component only (for example .3s or ,.2f). Mutually exclusive with format_preset.

      • delta - [object] - Overrides for a measure's comparison column, the Δ (delta) or Δ% (percent_change) column shown next to the measure while the component shows a time comparison. Only on measures of the metrics view; adhoc measures have no comparison columns.

        • width - [integer] - Column width in pixels, 60–300. The column keeps this width under stretch and fit_to_width.

      • percent_change - [object] - Overrides for a measure's comparison column, the Δ (delta) or Δ% (percent_change) column shown next to the measure while the component shows a time comparison. Only on measures of the metrics view; adhoc measures have no comparison columns.

        • width - [integer] - Column width in pixels, 60–300. The column keeps this width under stretch and fit_to_width.

  • measures - [array of oneOf] - List of measures to display. Each entry is a field name or an object with the name and per-column overrides. (required)

    • option 1 - [string] - Name of the dimension, measure, adhoc measure, or encoded time column (for example ts_rill_TIME_GRAIN_DAY)

    • option 2 - [object] - (no description)

      • name - [string] - Name of the dimension, measure, adhoc measure, or encoded time column (required)

      • width - [integer] - Column width in pixels. Measures and adhoc measures accept 60–300, dimensions and time columns 100–600. The column keeps this width under stretch and fit_to_width. Not allowed on col_dimensions, nor on row dimensions after the first.

      • wrap - [boolean] - Wrap the cell text over wrap_lines lines instead of truncating it; overrides the component-level wrap. Only on a table's dimension columns and on the first row dimension of a pivot.

      • align - [string] - Text alignment of the header and cells, for table columns and measures. Defaults to right for measures and left for dimensions. Not allowed on row_dimensions or col_dimensions.

      • label - [string] - Header text, replacing the display name from the metrics view.

      • format_preset - [string] - Number format preset for a measure in this component only. Mutually exclusive with format_d3.

      • format_d3 - [string] - d3 format string for a measure in this component only (for example .3s or ,.2f). Mutually exclusive with format_preset.

      • delta - [object] - Overrides for a measure's comparison column, the Δ (delta) or Δ% (percent_change) column shown next to the measure while the component shows a time comparison. Only on measures of the metrics view; adhoc measures have no comparison columns.

        • width - [integer] - Column width in pixels, 60–300. The column keeps this width under stretch and fit_to_width.

      • percent_change - [object] - Overrides for a measure's comparison column, the Δ (delta) or Δ% (percent_change) column shown next to the measure while the component shows a time comparison. Only on measures of the metrics view; adhoc measures have no comparison columns.

        • width - [integer] - Column width in pixels, 60–300. The column keeps this width under stretch and fit_to_width.

  • adhoc_measures - [array of object] - Adhoc measures defined on this component, derived from the metrics view's measures with an arithmetic expression. Reference them by name in measures. See Adhoc measures.

    • name - [string] - Name used to reference the measure. Must not match a dimension or measure in the metrics view. (required)

    • display_name - [string] - Label shown in the component. Defaults to name.

    • expression - [string] - Arithmetic expression over the metrics view's measure names, for example (revenue - cost) / revenue. (required)

    • format_preset - [string] - Format preset for the values. Defaults to humanize.

    • description - [string] - Text shown in the measure's tooltip instead of the expression.

  • time_range - [string] - Time range for the table (required)

  • row_dimensions - [array of oneOf] - Dimensions for pivot rows. The first one keys the merged row-header column, so only it takes width and wrap; row dimensions never take align.

    • option 1 - [string] - Name of the dimension, measure, adhoc measure, or encoded time column (for example ts_rill_TIME_GRAIN_DAY)

    • option 2 - [object] - (no description)

      • name - [string] - Name of the dimension, measure, adhoc measure, or encoded time column (required)

      • width - [integer] - Column width in pixels. Measures and adhoc measures accept 60–300, dimensions and time columns 100–600. The column keeps this width under stretch and fit_to_width. Not allowed on col_dimensions, nor on row dimensions after the first.

      • wrap - [boolean] - Wrap the cell text over wrap_lines lines instead of truncating it; overrides the component-level wrap. Only on a table's dimension columns and on the first row dimension of a pivot.

      • align - [string] - Text alignment of the header and cells, for table columns and measures. Defaults to right for measures and left for dimensions. Not allowed on row_dimensions or col_dimensions.

      • label - [string] - Header text, replacing the display name from the metrics view.

      • format_preset - [string] - Number format preset for a measure in this component only. Mutually exclusive with format_d3.

      • format_d3 - [string] - d3 format string for a measure in this component only (for example .3s or ,.2f). Mutually exclusive with format_preset.

      • delta - [object] - Overrides for a measure's comparison column, the Δ (delta) or Δ% (percent_change) column shown next to the measure while the component shows a time comparison. Only on measures of the metrics view; adhoc measures have no comparison columns.

        • width - [integer] - Column width in pixels, 60–300. The column keeps this width under stretch and fit_to_width.

      • percent_change - [object] - Overrides for a measure's comparison column, the Δ (delta) or Δ% (percent_change) column shown next to the measure while the component shows a time comparison. Only on measures of the metrics view; adhoc measures have no comparison columns.

        • width - [integer] - Column width in pixels, 60–300. The column keeps this width under stretch and fit_to_width.

  • col_dimensions - [array of oneOf] - Dimensions pivoted into column groups. They span their measure columns, so they take only name and label; set widths on the measures.

    • option 1 - [string] - Name of the dimension, measure, adhoc measure, or encoded time column (for example ts_rill_TIME_GRAIN_DAY)

    • option 2 - [object] - (no description)

      • name - [string] - Name of the dimension, measure, adhoc measure, or encoded time column (required)

      • width - [integer] - Column width in pixels. Measures and adhoc measures accept 60–300, dimensions and time columns 100–600. The column keeps this width under stretch and fit_to_width. Not allowed on col_dimensions, nor on row dimensions after the first.

      • wrap - [boolean] - Wrap the cell text over wrap_lines lines instead of truncating it; overrides the component-level wrap. Only on a table's dimension columns and on the first row dimension of a pivot.

      • align - [string] - Text alignment of the header and cells, for table columns and measures. Defaults to right for measures and left for dimensions. Not allowed on row_dimensions or col_dimensions.

      • label - [string] - Header text, replacing the display name from the metrics view.

      • format_preset - [string] - Number format preset for a measure in this component only. Mutually exclusive with format_d3.

      • format_d3 - [string] - d3 format string for a measure in this component only (for example .3s or ,.2f). Mutually exclusive with format_preset.

      • delta - [object] - Overrides for a measure's comparison column, the Δ (delta) or Δ% (percent_change) column shown next to the measure while the component shows a time comparison. Only on measures of the metrics view; adhoc measures have no comparison columns.

        • width - [integer] - Column width in pixels, 60–300. The column keeps this width under stretch and fit_to_width.

      • percent_change - [object] - Overrides for a measure's comparison column, the Δ (delta) or Δ% (percent_change) column shown next to the measure while the component shows a time comparison. Only on measures of the metrics view; adhoc measures have no comparison columns.

        • width - [integer] - Column width in pixels, 60–300. The column keeps this width under stretch and fit_to_width.

  • hide_totals_row - [boolean] - Whether to hide the totals row. Defaults to false.

  • hide_totals_col - [boolean] - Whether to hide the totals column. Defaults to false.

  • totals_row_position - [string] - Where to pin the totals row, either "top" (default) or "bottom".

  • row_limit - [string] - Maximum number of rows to display in a pivot table (one of "5", "10", "25", "50", "100"). Omit or set to "all" for all rows.

  • fit_to_width - [boolean] - When the columns overflow the component, shrink every column that has no configured width (down to its minimum) so the table fits instead of scrolling. Defaults to false.

  • wrap - [boolean] - Wrap the text of dimension cells over wrap_lines lines instead of truncating it. Defaults to false.

  • wrap_headers - [boolean] - Wrap header labels over wrap_lines lines instead of truncating them. Defaults to false.

  • wrap_lines - [integer] - Lines per row (and per header row) when wrapping is on, between 1 and 5. Defaults to 2.

  • sort_by - [string] - Initial sort field. In a table any column; in a pivot a measure (rows are ordered by its row total) or a row dimension. Viewers can still re-sort by clicking headers.

  • sort_comparison - [string] - Sort on the measure's comparison column instead of its value, delta or percent_change. Requires sort_by to name a measure of the metrics view (not an adhoc measure) and only applies while the component shows a time comparison; otherwise the measure's value is sorted.

  • sort_dir - [string] - Direction of the initial sort. Defaults to desc for measures and asc for dimensions.

  • comparison_range - [string] - Comparison time range

  • filter - [string] - Filter expression

  • title - [string] - Table title

  • description - [string] - Table description

pivot​

[object] - Pivot table

leaderboard​

[object] - Leaderboard

markdown​

[object] - (no description)

  • content - [string] - Markdown content (required)

  • css - [object] - CSS styles

  • title - [string] - Markdown title

  • description - [string] - Markdown description

image​

[object] - (no description)

  • url - [string] - Image URL. Used in light mode, and in dark mode when dark_url is not set. (required)

  • dark_url - [string] - Image URL to use when the dashboard is displayed in dark mode. Defaults to url.

  • css - [object] - CSS styles

  • title - [string] - Image title

  • description - [string] - Image description

custom_chart​

[object] - A custom visualization: a Metrics SQL query plus a chart spec describing how to draw it. Rill derives scales, axes, formats, sorting, stacking and layout from the data and from the metrics view's semantics, so the spec only states the chart type and which field goes on which channel. See Custom Viz.

  • metrics_sql - [string] - Metrics SQL query selecting the dimensions and measures to plot, e.g. SELECT {{ .params.dim }}, {{ .params.measure }} FROM {{ .params.metrics_view }} LIMIT 10. Measures arrive pre-aggregated; do not wrap them in aggregate functions.

  • spec - [object] - (no description)

    • chartType - [string] - The chart type, e.g. Line Chart, Bar Chart, Heatmap, Waterfall Chart. See Chart Types for the full list.

    • encodings - [object] - Maps a visual channel (x, y, x2, y2, color, size, column, row, group, goal, ...) to a field. Each value is either a field name or an encoding object.

    • chartProperties - [object] - Per-chart-type presentation tuning, e.g. innerRadius, stackMode, interpolate.

  • vega_spec - [string] - A Vega-Lite spec, as an alternative to spec for a chart Rill cannot describe. This is what converting a chart spec in the component editor produces: the Vega-Lite it compiled to, with the param bindings turned back into template references. Rill no longer derives scales, axes, formats, sorting or layout, so the chart stops adapting on its own. Read the query result from the query1 dataset, i.e. "data": {"name": "query1"}, and size the chart to its container with "width": "container", "height": "container" and "autosize": {"type": "fit", "contains": "padding"}. Mutually exclusive with spec. Template values are JSON-escaped, so place placeholders inside JSON strings. See Vega-Lite.

map​

[object] - Map of points or regions from a geo dimension, colored by a measure and, for points, sized by a second measure

  • metrics_view - [string] - Reference to the metrics view to use (required)

  • geo_dimension - [object] - Dimension that holds the location of each row, as a GeoJSON geometry string or a DuckDB POINT_2D or POLYGON_2D value, in longitude and latitude. Only dimensions with type: geo are offered in the visual editor. (required)

    • field - [string] - Name of the dimension (required)

    • type - [string] - Field type, always nominal

  • color - [object] - Measure that colors each point or region (required)

    • measure - [string] - Name of the measure (required)

    • colorRange - [object] - Color scale for the measure. Use mode: scheme with a scheme (sequential, diverging, tealblues, viridis, magma, inferno, plasma, cividis, blues, teals, greens, greys, oranges, purples, reds, turbo, spectral), or mode: gradient with start and end colors. Defaults to the tealblues scheme.

      • mode - [string] - Whether to use a named color scheme or a two-color gradient

      • scheme - [string] - Name of the color scheme, used when mode is scheme

      • start - [string] - Color for the lowest value, used when mode is gradient. A hex color, primary or secondary.

      • end - [string] - Color for the highest value, used when mode is gradient. A hex color, primary or secondary.

  • size_measure - [object] - Measure that scales the radius of each point. Points only; ignored for polygons.

    • field - [string] - Name of the measure (required)

    • type - [string] - Field type, always quantitative

  • tooltip_dimension - [object] - Dimension whose value is shown as the heading of the hover tooltip

    • field - [string] - Name of the dimension (required)

    • type - [string] - Field type, always nominal

  • initial_view - [object] - Camera position the map opens with. When set, the map does not zoom to fit the data.

    • longitude - [number] - Longitude of the map center (required)

    • latitude - [number] - Latitude of the map center (required)

    • zoom - [number] - Zoom level, from 0 (whole world) to about 22 (building level)

  • title - [string] - Map title

  • description - [string] - Map description

  • show_description_as_tooltip - [boolean] - Show the description as a tooltip on the title instead of below it

  • time_filters - [string] - Time range and comparison for this map, as tr and compare_tr URL parameters. Defaults to the canvas time range.

  • dimension_filters - [string] - SQL filter expression applied to this map only, such as country IN ('US')

  • hide_local_filters - [boolean] - Hide the local filter chips on the map; the filters still apply to its queries

Common Properties​

name​

[string] - Name is usually inferred from the filename, but can be specified manually.

refs​

[array of string] - List of resource references

tags​

[array of string] - Tags for organizing and filtering the resource (e.g. on the project dashboards list).

metadata​

[object] - User-defined key-value metadata attached to the resource. Rill does not read or write it; it is exposed as-is on the resource's meta over the API for external tooling. Values are strings, with numbers and booleans coerced. Not supported in rill.yaml defaults.

dev​

[object] - Overrides any properties in development environment.

prod​

[object] - Overrides any properties in production environment.