Section

Organize a page into named or unnamed regions.

A section block organizes part of a page without adding a bounded surface. It gives its content a common heading and spacing. Use a panel when the content must read as one bounded item.

A section has a main content region and an optional aside region. The renderer decides if these regions appear beside each other or in sequence.

API

section(title?: string): SectionBuilder

Method	Input	Result
`setDescription`	`string`	Adds supporting text under the title.
`setContent`	`Producer[]`	Sets the main content region.
`setAside`	`Producer[]`	Sets the secondary content region.
`setFilters`	`StateBinding<FilterBar>`	Places a filter bar in the section header.

Calling setContent or setAside again replaces the previous content for that region.

Basic section

Pass a title to section and add the main region with setContent.

import {
  callout,
  defineResource,
  section,
} from '@backlit/sdk'

const orders = defineResource('orders', [])

orders.view('detail', () =>
  section('Order status').setContent([
    callout('This order is ready to ship.'),
  ])
)

export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "detail",
    "slots": {
      "content": [
        {
          "kind": "section",
          "title": "Order status",
          "slots": {
            "content": [
              {
                "kind": "callout",
                "text": "This order is ready to ship."
              }
            ]
          }
        }
      ]
    }
  }
}

Untitled section

Omit the title when the content already reads as one region without a heading.

import {
  callout,
  defineResource,
  section,
} from '@backlit/sdk'

const orders = defineResource('orders', [])

orders.view('detail', () =>
  section().setContent([
    callout('This order is ready to ship.'),
  ])
)

export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "detail",
    "slots": {
      "content": [
        {
          "kind": "section",
          "slots": {
            "content": [
              {
                "kind": "callout",
                "text": "This order is ready to ship."
              }
            ]
          }
        }
      ]
    }
  }
}

Description

Add a description when the title does not give sufficient context.

import {
  callout,
  defineResource,
  section,
} from '@backlit/sdk'

const orders = defineResource('orders', [])

orders.view('detail', () =>
  section('Order status')
    .setDescription('Current payment and shipment state.')
    .setContent([callout('This order is ready to ship.')])
)

export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "detail",
    "slots": {
      "content": [
        {
          "kind": "section",
          "title": "Order status",
          "description": "Current payment and shipment state.",
          "slots": {
            "content": [
              {
                "kind": "callout",
                "text": "This order is ready to ship."
              }
            ]
          }
        }
      ]
    }
  }
}

Content

The content region accepts multiple blocks and preserves their order.

import {
  callout,
  defineResource,
  section,
} from '@backlit/sdk'

const orders = defineResource('orders', [])

orders.view('detail', () =>
  section('Order status').setContent([
    callout('Payment is complete.').setTone('success'),
    callout('The order is ready to ship.').setTone('info'),
  ])
)

export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "detail",
    "slots": {
      "content": [
        {
          "kind": "section",
          "title": "Order status",
          "slots": {
            "content": [
              {
                "kind": "callout",
                "text": "Payment is complete.",
                "tone": "success"
              },
              {
                "kind": "callout",
                "text": "The order is ready to ship.",
                "tone": "info"
              }
            ]
          }
        }
      ]
    }
  }
}

Aside

Use setAside for related content that is secondary to the main region. The protocol defines the relationship, not the screen layout.

import {
  callout,
  defineResource,
  panel,
  section,
} from '@backlit/sdk'

const orders = defineResource('orders', [])

orders.view('detail', () =>
  section('Order')
    .setContent([
      panel([
        callout('The order is ready to ship.'),
      ]).setTitle('Activity'),
    ])
    .setAside([
      panel([callout('A. Customer')]).setTitle('Customer'),
    ])
)

export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "detail",
    "slots": {
      "content": [
        {
          "kind": "section",
          "title": "Order",
          "slots": {
            "content": [
              {
                "kind": "panel",
                "title": "Activity",
                "slots": {
                  "content": [
                    {
                      "kind": "callout",
                      "text": "The order is ready to ship."
                    }
                  ]
                }
              }
            ],
            "aside": [
              {
                "kind": "panel",
                "title": "Customer",
                "slots": {
                  "content": [
                    {
                      "kind": "callout",
                      "text": "A. Customer"
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Nested section

Place a section inside another section to divide a region into smaller named parts.

import {
  callout,
  defineResource,
  section,
} from '@backlit/sdk'

const orders = defineResource('orders', [])

orders.view('detail', () =>
  section('Order').setContent([
    section('Shipment').setContent([
      callout('The order is ready to ship.'),
    ]),
  ])
)

export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "detail",
    "slots": {
      "content": [
        {
          "kind": "section",
          "title": "Order",
          "slots": {
            "content": [
              {
                "kind": "section",
                "title": "Shipment",
                "slots": {
                  "content": [
                    {
                      "kind": "callout",
                      "text": "The order is ready to ship."
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Filters

Pass the filter binding from the current view or zone. The renderer places the filter controls in the section header.

import {
  callout,
  defineFilters,
  defineResource,
  filters,
  section,
} from '@backlit/sdk'

const orders = defineResource('orders', [])
const orderFilters = defineFilters([
  filters.text('search').setLabel('Search orders'),
])

orders.view(
  'detail',
  { filters: orderFilters },
  (_ctx, view) =>
    section('Orders')
      .setFilters(view.state.filters)
      .setContent([
        callout('Three orders match the current search.'),
      ])
)

export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "detail",
    "slots": {
      "content": [
        {
          "kind": "section",
          "title": "Orders",
          "slots": {
            "content": [
              {
                "kind": "callout",
                "text": "Three orders match the current search."
              }
            ],
            "filters": {
              "kind": "filters",
              "resource": "orders",
              "view": "detail",
              "keyword": "f",
              "definesResult": true,
              "dependsOnResult": false,
              "filters": [
                {
                  "kind": "text",
                  "name": "search",
                  "label": "Search orders"
                }
              ]
            }
          }
        }
      ]
    }
  }
}

All options

You can use a title, description, filters, main content, and aside content in one section.

import {
  callout,
  defineFilters,
  defineResource,
  filters,
  panel,
  section,
} from '@backlit/sdk'

const orders = defineResource('orders', [])
const orderFilters = defineFilters([
  filters.text('search').setLabel('Search activity'),
])

orders.view(
  'detail',
  { filters: orderFilters },
  (_ctx, view) =>
    section('Order activity')
      .setDescription(
        'Payment and shipment updates for this order.'
      )
      .setFilters(view.state.filters)
      .setContent([
        panel([
          callout('The order left the warehouse at 09:30.'),
        ]).setTitle('Timeline'),
      ])
      .setAside([
        panel([callout('A. Customer')]).setTitle(
          'Customer'
        ),
      ])
)

export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "detail",
    "slots": {
      "content": [
        {
          "kind": "section",
          "title": "Order activity",
          "description": "Payment and shipment updates for this order.",
          "slots": {
            "content": [
              {
                "kind": "panel",
                "title": "Timeline",
                "slots": {
                  "content": [
                    {
                      "kind": "callout",
                      "text": "The order left the warehouse at 09:30."
                    }
                  ]
                }
              }
            ],
            "aside": [
              {
                "kind": "panel",
                "title": "Customer",
                "slots": {
                  "content": [
                    {
                      "kind": "callout",
                      "text": "A. Customer"
                    }
                  ]
                }
              }
            ],
            "filters": {
              "kind": "filters",
              "resource": "orders",
              "view": "detail",
              "keyword": "f",
              "definesResult": true,
              "dependsOnResult": false,
              "filters": [
                {
                  "kind": "text",
                  "name": "search",
                  "label": "Search activity"
                }
              ]
            }
          }
        }
      ]
    }
  }
}

setActions([visitTo(...), submitTo(...)]) replaces the header controls. Each control requires text or an icon. These blocks have no row, so supply fixed argument values. See Targets. revealWhen(condition) controls the block inside a form. It has no enable condition. See Form conditions.