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

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

custom_chart​

[object] - Custom Vega-Lite chart built from Metrics SQL queries

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

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.