Customize the layout of a workbook in code representation (Beta)

This documentation describes one or more public beta features that are in development. Beta features are subject to quick, iterative changes; therefore the current user experience in the Sigma service can differ from the information provided in this page.

This page should not be considered official published documentation until Sigma removes this notice and the beta flag on the corresponding feature(s) in the Sigma service. For the full beta feature disclaimer, see Beta features.

You can customize the layout of a workbook page in the code representation using the contents.layout field. The layout field is an XML string that controls which page each element belongs to, and the size and position of each element on that page using a 24-column grid system. To control how elements are arranged on a page when you create or update a workbook using the API, specify the layout in the representation.

When you retrieve the representation of an existing workbook using the Get a workbook endpoint with includeContents=true, the layout field populates automatically based on the arrangement of elements on each page in the published version.

The layout field is required. Every element in contents.elements must be placed in the layout, because the layout is what assigns an element to a page. A representation with an element the layout never references is rejected with an error naming that element, such as elements[0]: element 'ammWveJOET' is not placed in layout.

Example representation with layout

The following example shows a YAML representation of a workbook with a table and a bar chart. Both elements span the full width of the page and are stacked vertically, one above the other.

YAML representation with layout

workbookId: bc9e239e-6e00-4f0f-a5b1-2e16df3245a2
workbookUrlId: K6nD3mi0cQAx9f8rriM64z
createdBy: TnQGIaVmMru7kyHwWPCQfUWjypPtZ
updatedBy: TnQGIaVmMru7kyHwWPCQfUWjypPtZ
createdAt: '2026-04-20T20:09:52.987Z'
updatedAt: '2026-04-21T14:22:44.075Z'
name: bar-chart
url: https://aws-api.sigmacomputing.com/org-name/workbook/bar-chart-K6nD3mi0cQAx9f8rriM64z
path: Examples
latestVersion: 2
ownerId: TnQGIaVmMru7kyHwWPCQfUWjypPtZ
isArchived: false
contents:
  schemaVersion: 1
  kind: workbook
  elements:
    - id: ammWveJOET
      kind: table
      source:
        connectionId: 6944db1a-f9f0-496f-91ba-4781e7f0490d
        kind: warehouse-table
        path:
          - FUN
          - BIKES
          - TRIP
      columns:
        - id: VGGdL5h1XL
          formula: '[TRIP/Id]'
        - id: XfekGVjpYe
          formula: '[TRIP/Duration]'
        - id: vSNXcQlbgo
          formula: '[TRIP/Start Date]'
        - id: n0viQISda6
          formula: '[TRIP/Start Station Name]'
        - id: otGGHmPqJZ
          formula: '[TRIP/Start Station Id]'
        - id: jrQpKNxZxF
          formula: '[TRIP/End Date]'
        - id: xT5p03z0yD
          formula: '[TRIP/End Station Name]'
        - id: kctIxpAAqM
          formula: '[TRIP/End Station Id]'
        - id: VwSnzv10lZ
          formula: '[TRIP/Bike Id]'
        - id: pxvj425aDk
          formula: '[TRIP/Subscription Type]'
        - id: HZOjVcwDG1
          formula: '[TRIP/Zip Code]'
      order:
        - VGGdL5h1XL
        - XfekGVjpYe
        - vSNXcQlbgo
        - n0viQISda6
        - otGGHmPqJZ
        - jrQpKNxZxF
        - xT5p03z0yD
        - kctIxpAAqM
        - VwSnzv10lZ
        - pxvj425aDk
        - HZOjVcwDG1
    - id: LBMxXnUDCS
      kind: bar-chart
      source:
        elementId: ammWveJOET
        kind: table
      columns:
        - id: xwi1BMJ3PL
          formula: '[TRIP/Start Station Name]'
        - id: vKP79P5tMl
          formula: Count([Id])
        - id: HlVOO3VkmU
          formula: '[TRIP/Subscription Type]'
        - id: 7vIMaF82Ea
          formula: '[TRIP/Id]'
        - id: OaVsOl70Mu
          formula: '[TRIP/Duration]'
        - id: 2EupEbY2C1
          formula: '[TRIP/Start Date]'
        - id: cOt55IxOwt
          formula: '[TRIP/Start Station Id]'
        - id: pOeY8EgDKh
          formula: '[TRIP/End Date]'
        - id: YvYBibU28Y
          formula: '[TRIP/End Station Name]'
        - id: W8iYZkmMus
          formula: '[TRIP/End Station Id]'
        - id: 9xgXlflRhB
          formula: '[TRIP/Bike Id]'
        - id: eBbsizX2wU
          formula: '[TRIP/Zip Code]'
      yAxis:
        - id: vKP79P5tMl
      xAxis:
        id: xwi1BMJ3PL
        sort:
          by: vKP79P5tMl
          direction: descending
  pages:
    - id: QKIgFmOpQt
      name: Page 1
  layout: |
    <?xml version="1.0" encoding="utf-8"?>
    <Page type="grid" gridTemplateColumns="repeat(24, 1fr)" gridTemplateRows="auto" id="QKIgFmOpQt">
      <Element elementId="ammWveJOET" gridColumn="1 / 25" gridRow="1 / 21"/>
      <Element elementId="LBMxXnUDCS" gridColumn="1 / 25" gridRow="21 / 41"/>
    </Page>
documentVersion: 2

Representing layout

In this example representation, the layout for Page 1 is defined in the layout field.

Layout representation

layout: |
  <?xml version="1.0" encoding="utf-8"?>
  <Page type="grid" gridTemplateColumns="repeat(24, 1fr)" gridTemplateRows="auto" id="QKIgFmOpQt">
    <Element elementId="ammWveJOET" gridColumn="1 / 25" gridRow="1 / 21"/>
    <Element elementId="LBMxXnUDCS" gridColumn="1 / 25" gridRow="21 / 41"/>
  </Page>

The layout field contains one <Page> element per workbook page. The id attribute of <Page> must match the id of the corresponding page in the contents.pages array. Inside <Page>, each <Element> entry places one element on that page — the elementId attribute must match the id of the corresponding element in the contents.elements array.

The gridColumn attribute controls the horizontal position and width of an element. The grid is 1-indexed across 24 columns, where 1 is the left edge and 25 is the right edge. For example, "1 / 25" spans the full width, "1 / 13" spans the left half, and "13 / 25" spans the right half.

The gridRow attribute controls the vertical position and height of an element. In this example, "1 / 21" places the table at the top of the page and "21 / 41" places the bar chart directly below it.

Layout tags

The layout field supports the following tags:

Tag	Description
`<Page>`	One workbook page. The `id` attribute must match the `id` of a page in `contents.pages`. A modal is also represented as a `<Page>`, whose `id` matches an entry in `contents.overlays`.
`<Element>`	One element placed on a page, in a container, or in a tab. The `elementId` attribute must match the `id` of an element in `contents.elements`.
`<Container>`	A container element. The `elementId` attribute must match the `id` of a `container` element in `contents.elements`. Nest an `<Element>` for each element inside the container.
`<TabbedContainer>`	A tabbed container element. The `elementId` attribute must match the `id` of a `tabbed-container` element in `contents.elements`. Nest one `<Tab>` per tab.
`<Tab>`	One tab inside a `<TabbedContainer>`. Nest an `<Element>` for each element in that tab. Tab order in the layout matches the order of the `tabs` array on the tabbed container element.

The following example places a table and a pivot table inside a container:

layout: |
  <?xml version="1.0" encoding="utf-8"?>
  <Page type="grid" gridTemplateColumns="repeat(24, 1fr)" gridTemplateRows="auto" id="QKIgFmOpQt">
    <Container elementId="B9DoZzOllO" type="grid" gridColumn="1 / 25" gridRow="1 / 41" gridTemplateColumns="repeat(24, 1fr)" gridTemplateRows="auto">
      <Element elementId="QBzbVN4mCL" gridColumn="1 / 25" gridRow="1 / 21"/>
      <Element elementId="1CFkfKbYWo" gridColumn="1 / 25" gridRow="21 / 41"/>
    </Container>
  </Page>

The container and both nested elements are siblings in the flat contents.elements array; only the layout expresses that the table and pivot table sit inside the container.