Widget group

Display related widgets as one set.

A widget group tells the renderer that its widgets belong together. The group has no title or layout options. Use a section to give the group a title. The renderer controls the screen layout.

The group accepts widgets and zones that produce widgets. It does not accept other blocks.

API

widgets.group(widgets: Producer<Widget>[]): WidgetGroupBuilder

Pass the complete content when you create the group. The builder has no other methods.

Basic group

A group can contain one widget when its relationship to other page content must remain explicit.

import {
  defineResource,
  fields,
  widget,
  widgets,
} from '@backlit/sdk'

const orders = defineResource('orders', [])
const revenue = fields.number('revenue', {
  format: 'currency',
  currency: 'USD',
})

orders.view('overview', () =>
  widgets.group([
    widget()
      .setTitle('Total revenue')
      .setStat({ value: 48_120, field: revenue }),
  ])
)

export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "overview",
    "slots": {
      "content": [
        {
          "kind": "widget-group",
          "slots": {
            "content": [
              {
                "kind": "widget",
                "title": "Total revenue",
                "stat": {
                  "value": 48120,
                  "field": {
                    "kind": "number",
                    "name": "revenue",
                    "format": "currency",
                    "currency": "USD",
                    "label": ""
                  },
                  "delta": "absolute"
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Multiple widgets

Pass related widgets in their display order.

import {
  defineResource,
  fields,
  widget,
  widgets,
} from '@backlit/sdk'

const orders = defineResource('orders', [])
const revenue = fields.number('revenue', {
  format: 'currency',
  currency: 'USD',
})
const count = fields.number('count', { format: 'integer' })
const rate = fields.number('rate', {
  format: 'percent',
  decimals: 1,
})

orders.view('overview', () =>
  widgets.group([
    widget()
      .setTitle('Total revenue')
      .setStat({ value: 48_120, field: revenue }),
    widget()
      .setTitle('Orders')
      .setStat({ value: 1_204, field: count }),
    widget()
      .setTitle('Refund rate')
      .setStat({ value: 0.018, field: rate }),
  ])
)

export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "overview",
    "slots": {
      "content": [
        {
          "kind": "widget-group",
          "slots": {
            "content": [
              {
                "kind": "widget",
                "title": "Total revenue",
                "stat": {
                  "value": 48120,
                  "field": {
                    "kind": "number",
                    "name": "revenue",
                    "format": "currency",
                    "currency": "USD",
                    "label": ""
                  },
                  "delta": "absolute"
                }
              },
              {
                "kind": "widget",
                "title": "Orders",
                "stat": {
                  "value": 1204,
                  "field": {
                    "kind": "number",
                    "name": "count",
                    "format": "integer",
                    "label": ""
                  },
                  "delta": "absolute"
                }
              },
              {
                "kind": "widget",
                "title": "Refund rate",
                "stat": {
                  "value": 0.018,
                  "field": {
                    "kind": "number",
                    "name": "rate",
                    "format": "percent",
                    "decimals": 1,
                    "label": ""
                  },
                  "delta": "absolute"
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Zones in a group

A zone can produce a widget inside a group. The SDK checks that the zone produces a widget and not another block type.

import {
  defineResource,
  fields,
  widget,
  widgets,
  zone,
} from '@backlit/sdk'

const orders = defineResource('orders', [])
const revenue = fields.number('revenue', {
  format: 'currency',
  currency: 'USD',
})
const count = fields.number('count', { format: 'integer' })

orders.view('overview', () =>
  widgets.group([
    zone('revenue', () =>
      widget()
        .setTitle('Total revenue')
        .setStat({ value: 48_120, field: revenue })
    ),
    zone('order-count', () =>
      widget()
        .setTitle('Orders')
        .setStat({ value: 1_204, field: count })
    ),
  ])
)

export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "overview",
    "slots": {
      "content": [
        {
          "kind": "widget-group",
          "slots": {
            "content": [
              {
                "kind": "zone",
                "name": "revenue",
                "resource": "orders",
                "view": "overview",
                "slots": {
                  "content": [
                    {
                      "kind": "widget",
                      "title": "Total revenue",
                      "stat": {
                        "value": 48120,
                        "field": {
                          "kind": "number",
                          "name": "revenue",
                          "format": "currency",
                          "currency": "USD",
                          "label": ""
                        },
                        "delta": "absolute"
                      }
                    }
                  ]
                }
              },
              {
                "kind": "zone",
                "name": "order-count",
                "resource": "orders",
                "view": "overview",
                "slots": {
                  "content": [
                    {
                      "kind": "widget",
                      "title": "Orders",
                      "stat": {
                        "value": 1204,
                        "field": {
                          "kind": "number",
                          "name": "count",
                          "format": "integer",
                          "label": ""
                        },
                        "delta": "absolute"
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  }
}