Grid

Grid manifests define CSS grid-based layouts with row and column headers, allowing you to organize child components in a structured tabular format. Grids are useful for creating dashboards, comparison views, and data matrices where components need to be arranged in rows and columns.

Minimal definition

This is the smallest well-formed Grid: the required headers and children plus chartTitle, which every grid should set - without it the title area is omitted and the matrix carries no message.

apiVersion: bino.bi/v1alpha1
kind: Grid
metadata:
  name: product-comparison
spec:
  chartTitle: Product Performance Matrix
  rowHeaders:
    - label: Laptops
      id: laptops
    - label: Tablets
      id: tablets
  columnHeaders:
    - label: Revenue
      id: rev
    - label: Trend
      id: trend
  children:
    - row: laptops
      column: rev
      kind: Text
      spec:
        dataset: laptop-revenue
        value: "${data['laptop-revenue'][0].total_revenue} EUR"
    - row: laptops
      column: trend
      kind: ChartTime
      ref: laptop-trend-chart
    - row: tablets
      column: rev
      kind: Text
      spec:
        dataset: tablet-revenue
        value: "${data['tablet-revenue'][0].total_revenue} EUR"
    - row: tablets
      column: trend
      kind: ChartTime
      ref: tablet-trend-chart

Headers also accept a plain list of labels instead of the explicit label/id objects (see Header formats), and a cell is either inline (kind + spec) or a reference to a standalone document (kind + ref, see Child references and inline definitions).

All attributes are listed in the Attribute Reference below.

Fields

Headers

Field	Type	Default	Description
chartTitle	string	""	Title displayed at the top-left of the grid.
rowHeaders	array	(required)	Row header definitions, at least one. Can be simple strings or objects with both label and id.
columnHeaders	array	(required)	Column header definitions, at least one. Can be simple strings or objects with both label and id.

Row and column headers support two formats:

Simple format - Labels only, IDs are auto-generated as 0, 1, 2, etc.:

rowHeaders:
  - Electronics
  - Apparel
  - Home & Garden
columnHeaders:
  - Q1
  - Q2
  - Q3

Explicit format - Custom IDs for child references:

rowHeaders:
  - label: Electronics
    id: electronics
  - label: Apparel
    id: apparel
columnHeaders:
  - label: Q1 2024
    id: q1
  - label: Q2 2024
    id: q2

Display options

Field	Type	Default	Description
showRowHeaders	boolean	true	Whether to display the row headers column.
showColumnHeaders	boolean	true	Whether to display the column headers row.
showBorders	boolean	true	Whether to display border/divider lines between cells.
rowHeaderWidth	string	"auto"	CSS width of the row header column (e.g., "auto", "100px", "20%").
cellGap	string	"0px"	CSS gap between grid cells (e.g., "0px", "8px").
selectedStyle	string	-	Name of a ComponentStyle manifest to apply; merged over the _system and _default styles.

Children

Field	Type	Description
children	array	Array of child definitions, at least one. Each child specifies its grid position and content.

Each child object has these properties:

Property	Type	Required	Description
row	string or integer	Yes	Row identifier matching a row ID from rowHeaders. Can be string or integer.
column	string or integer	Yes	Column identifier matching a column ID from columnHeaders. Can be string or integer.
kind	string	Yes	Component type: Text, Table, ChartStructure, ChartTime, ChartScatter, ChartBubble, ChartBullet, Tree, or Image.
ref	string	No	Reference to a standalone component document by name.
optional	boolean	No	When true, skip gracefully if ref is missing (default: false).
params	object	No	Parameter values (string map) passed to the referenced document. Only valid together with ref.
spec	object	Conditional	Component specification. Required for inline children, optional override for ref children.
metadata	object	No	Optional metadata including name and constraints.

---

Child references and inline definitions

Grid children can reference existing component documents or define components inline.

Reference to existing component

children:
  - row: electronics
    column: q1
    kind: ChartStructure
    ref: electronics-q1-chart

If the referenced document declares parameters in metadata.params, pass values with params (see LayoutPage parameters):

children:
  - row: electronics
    column: q1
    kind: ChartStructure
    ref: quarterly-chart
    params:
      QUARTER: "q1"

Inline component definition

children:
  - row: electronics
    column: q2
    kind: Table
    spec:
      dataset: sales-data
      scenarios: ac,fc

Reference with overrides

Combine a reference with inline spec to override specific properties:

children:
  - row: electronics
    column: q3
    kind: ChartStructure
    ref: electronics-base-chart
    spec:
      chartTitle: Q3 Electronics # Override the base chart's title
      filter: quarter == 'Q3' # Add a filter

Optional references

Mark a reference as optional to skip the child gracefully if the referenced component doesn’t exist:

children:
  - row: home
    column: q3
    kind: Table
    ref: home-q3-table
    optional: true # Skip if not found instead of erroring

---

Constraint-based children

Children can include constraints that determine if they appear based on artefact labels, spec fields, or execution mode:

children:
  - row: electronics
    column: q1
    kind: ChartStructure
    ref: detailed-chart
    metadata:
      name: detailed-electronics-q1
      constraints:
        - mode == build
        - labels.detail == high
  - row: electronics
    column: q1
    kind: Text
    spec:
      value: "Summary view"
    metadata:
      name: summary-electronics-q1
      constraints:
        - mode == preview

---

Using Grid in layouts

Grid can be used as a child component in LayoutPage or LayoutCard:

Standalone Grid document

With simple headers, use integers for row/column references:

---
apiVersion: bino.bi/v1alpha1
kind: Grid
metadata:
  name: sales-matrix
spec:
  rowHeaders: [North, South, East, West]
  columnHeaders: [Revenue, Units, Margin]
  children:
    - row: 0
      column: 0
      kind: Text
      spec:
        dataset: north-revenue
        value: "${data['north-revenue'][0].revenue}"
    - row: 0
      column: 1
      kind: Text
      spec:
        dataset: north-units
        value: "${data['north-units'][0].units}"
    # ... more children

Reference in LayoutPage

---
apiVersion: bino.bi/v1alpha1
kind: LayoutPage
metadata:
  name: dashboard
spec:
  pageLayout: full
  children:
    - kind: Grid
      ref: sales-matrix

Inline Grid in LayoutPage

---
apiVersion: bino.bi/v1alpha1
kind: LayoutPage
metadata:
  name: dashboard
spec:
  pageLayout: full
  children:
    - kind: Grid
      metadata:
        name: inline-grid
      spec:
        chartTitle: Inline Grid Example
        rowHeaders: [A, B]
        columnHeaders: [X, Y]
        children:
          - row: 0
            column: 0
            kind: Text
            spec:
              value: "Cell A-X"
          - row: 1
            column: 1
            kind: Text
            spec:
              value: "Cell B-Y"

---

Complete example

A product comparison grid with multiple component types:

---
apiVersion: bino.bi/v1alpha1
kind: Grid
metadata:
  name: product-comparison
  description: Quarterly product performance comparison
spec:
  chartTitle: Product Performance Matrix
  rowHeaders:
    - label: Laptops
      id: laptops
    - label: Tablets
      id: tablets
    - label: Phones
      id: phones
  columnHeaders:
    - label: Revenue
      id: rev
    - label: Units Sold
      id: units
    - label: Trend
      id: trend
  showRowHeaders: true
  showColumnHeaders: true
  showBorders: true
  rowHeaderWidth: 120px
  cellGap: 4px
  children:
    # Laptop row
    - row: laptops
      column: rev
      kind: Text
      spec:
        dataset: laptop-revenue
        value: "${data['laptop-revenue'][0].total_revenue} EUR"
    - row: laptops
      column: units
      kind: Text
      spec:
        dataset: laptop-units
        value: "${data['laptop-units'][0].units_sold}"
    - row: laptops
      column: trend
      kind: ChartTime
      ref: laptop-trend-chart

    # Tablet row
    - row: tablets
      column: rev
      kind: Table
      ref: tablet-revenue-table
    - row: tablets
      column: units
      kind: Text
      spec:
        dataset: tablet-units
        value: "${data['tablet-units'][0].units_sold}"
    - row: tablets
      column: trend
      kind: ChartTime
      ref: tablet-trend-chart

    # Phone row
    - row: phones
      column: rev
      kind: ChartStructure
      ref: phone-revenue-chart
    - row: phones
      column: units
      kind: Text
      spec:
        dataset: phone-units
        value: "${data['phone-units'][0].units_sold}"
    - row: phones
      column: trend
      kind: ChartTime
      ref: phone-trend-chart

---

Styling

Grid appearance is controlled via ComponentStyle under the bn-grid key:

apiVersion: bino.bi/v1alpha1
kind: ComponentStyle
metadata:
  name: custom-style
spec:
  content:
    bn-grid:
      headerBackground: "#f5f5f5"
      borderColor: "#cccccc"
      borderWidth: 1
      cellPadding: 8

See ComponentStyle for all available grid styling options.

Attribute Reference

Common Metadata

Attribute	Type	Required	Default	Description
apiVersion	string	yes	-	Must be bino.bi/v1alpha1.
kind	string	yes	-	Must be Grid.
metadata.name	string	yes	-	Unique identifier.
metadata.labels	object	no	-	Key-value pairs for categorization and constraint matching.
metadata.annotations	object	no	-	Arbitrary key-value metadata, not used by the system.
metadata.description	string	no	-	Free-form description.
metadata.constraints	array	no	-	Conditional inclusion rules. See Constraints.
metadata.params	array	no	-	Typed parameters expected when this grid is referenced with params. Same structure as LayoutPage parameters.

Spec Attributes

Attribute	Type	Required	Default	Description	Sample
spec.chartTitle	string	no	""	Title displayed at the top-left of the grid. If empty, the title area is omitted.	chartTitle: "Regional Sales Overview"
spec.rowHeaders	array	yes	-	Row header definitions, at least one entry. Simple strings (IDs auto-generated as 0, 1, 2…) or objects with label and id.	rowHeaders: [North, South]
spec.rowHeaders[].label	string	yes	-	Display text for the row header. Required in the object form.	label: Electronics
spec.rowHeaders[].id	string	yes	-	Unique identifier for the row, used in cell references. Required in the object form.	id: electronics
spec.columnHeaders	array	yes	-	Column header definitions, at least one entry. Simple strings or objects with label and id.	columnHeaders: [Q1, Q2, Q3]
spec.columnHeaders[].label	string	yes	-	Display text for the column header. Required in the object form.	label: Q1 2024
spec.columnHeaders[].id	string	yes	-	Unique identifier for the column, used in cell references. Required in the object form.	id: q1
spec.showRowHeaders	boolean	no	true	Display the row headers column.	showRowHeaders: true
spec.showColumnHeaders	boolean	no	true	Display the column headers row.	showColumnHeaders: true
spec.showBorders	boolean	no	true	Display border/divider lines between cells.	showBorders: false
spec.rowHeaderWidth	string	no	"auto"	CSS width of the row header column (e.g. auto, 100px, 20%).	rowHeaderWidth: "120px"
spec.cellGap	string	no	"0px"	CSS gap between grid cells (e.g. 0px, 8px).	cellGap: "8px"
spec.selectedStyle	string	no	-	Name of a ComponentStyle manifest to apply. Merged over the _system and _default styles. Maps to the selected-style HTML attribute.	selectedStyle: corporate-style
spec.i18nNamespace	string	no	-	I18n namespace inherited by the grid’s children (their own i18nNamespace wins). Resolved from the enclosing artefact, page or card when not set. Maps to the i18n-namespace HTML attribute.	i18nNamespace: sales
spec.children	array	yes	-	Array of grid child definitions specifying position and content, at least one entry.	see below

Header formats

Simple format - labels only, IDs are auto-generated:

spec:
  rowHeaders: [Electronics, Apparel, Home]
  columnHeaders: [Q1, Q2, Q3]

Explicit format - custom IDs for child references:

spec:
  rowHeaders:
    - label: Electronics
      id: electronics
    - label: Apparel
      id: apparel
  columnHeaders:
    - label: Q1 2024
      id: q1
    - label: Q2 2024
      id: q2

Grid child object

spec:
  children:
    - row: electronics # must match rowHeaders ID
      column: q1 # must match columnHeaders ID
      kind: ChartStructure # see the kind values below
      ref: my-chart # optional reference to standalone document
      optional: false # skip gracefully if ref is missing
      spec: # inline spec or override for ref
        chartTitle: "Q1 Sales"
      metadata: # optional metadata
        name: cell-name
        constraints:
          - mode==build

Property	Type	Required	Default	Description	Sample
children[].row	string or integer	yes	-	Row identifier matching a row ID from rowHeaders (or the auto-generated index).	row: electronics
children[].column	string or integer	yes	-	Column identifier matching a column ID from columnHeaders (or the auto-generated index).	column: q1
children[].kind	string	yes	-	Component type. Values: Text, Table, ChartStructure, ChartTime, ChartScatter, ChartBubble, ChartBullet, Tree, Image.	kind: ChartStructure
children[].ref	string	no	-	Reference to standalone document by name (metadata.name). The referenced spec is used as the base.	ref: electronics-q1-chart
children[].optional	boolean	no	false	Skip gracefully if ref is missing.	optional: true
children[].params	object of string	no	-	Parameter values passed to the referenced document, expanded as ${NAME} in its spec. Only valid together with ref.	params: { QUARTER: "q1" }
children[].spec	object	conditional	-	Component specification. Required for inline children, optional override for ref children.	spec: { dataset: sales-data }
children[].metadata	object	no	-	Optional metadata including name and constraints.	metadata: { name: cell-name }