> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://help.sigmacomputing.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.sigmacomputing.com/_mcp/server. # Customize the layout of a report in code representation (Beta) > Customize Sigma report layout in code using the layout field to position elements by pixel coordinates, and the config field for page size and margins. 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](/docs/sigma-product-releases#beta-features). You can customize the layout of a report in the [code representation](/docs/manage-reports-as-code) using the `contents.layout` and `contents.config` fields. The `layout` field is an XML string that controls which page or panel each element belongs to, and the size and position of each element there. The `config` field controls page-level configurations, including the page size and margins. To control how elements are arranged on a page when you create or update a report using the API, specify the `layout` in the representation. When you retrieve the representation of an existing report using the [Get a report](/reference/get-report) endpoint with `includeContents=true`, the `layout` and `config` fields populate automatically based on the published version of the report. 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 or panel. A representation with an element the layout never references is rejected with an error naming that element, such as `elements[0]: element 'Vg934XlZ_4' is not placed in layout`. ## Example representation with layout The following example shows a YAML representation of a report with a table and a line chart. Both elements span the full width of the page (excluding the margins) and are stacked vertically, with the line chart directly below the table. #### YAML representation with layout ```yaml reportId: 5353ba23-a5eb-4950-b82a-b04dacc102e1 reportUrlId: 2xeCQoI36qYlYVQC9JaFKV createdBy: sKsOdrKB6Gwn4YEHnq0D0CO8CPlg4 updatedBy: sKsOdrKB6Gwn4YEHnq0D0CO8CPlg4 createdAt: '2026-07-27T00:28:16.201Z' updatedAt: '2026-07-31T20:59:35.325Z' name: Weather Report url: https://staging.sigmacomputing.io/org-slug/report/Weather-Report-2xeCQoI36qYlYVQC9JaFKV path: Examples latestVersion: 6 ownerId: sKsOdrKB6Gwn4YEHnq0D0CO8CPlg4 isArchived: false documentVersion: 6 contents: schemaVersion: 1 kind: report elements: - id: fDH5mMDdwi kind: table source: connectionId: 88c88ad1-eee1-4220-bd54-75125ccedc77 kind: warehouse-table path: - SAMPLE_CONNECTION_FUN - BIKES - WEATHER columns: - id: inode-l8GQlchbkER0Af7BOfjtNa/DATE formula: '[WEATHER/Date]' - id: inode-l8GQlchbkER0Af7BOfjtNa/MAX_TEMPERATURE_F formula: '[WEATHER/Max Temperature F]' - id: inode-l8GQlchbkER0Af7BOfjtNa/MEAN_TEMPERATURE_F formula: '[WEATHER/Mean Temperature F]' - id: inode-l8GQlchbkER0Af7BOfjtNa/MIN_TEMPERATURE_F formula: '[WEATHER/Min Temperature F]' order: - inode-l8GQlchbkER0Af7BOfjtNa/DATE - inode-l8GQlchbkER0Af7BOfjtNa/MAX_TEMPERATURE_F - inode-l8GQlchbkER0Af7BOfjtNa/MEAN_TEMPERATURE_F - inode-l8GQlchbkER0Af7BOfjtNa/MIN_TEMPERATURE_F visibleAsSource: false - id: n86TkVYCM7 kind: line-chart source: connectionId: 88c88ad1-eee1-4220-bd54-75125ccedc77 kind: warehouse-table path: - SAMPLE_CONNECTION_FUN - BIKES - WEATHER columns: - id: yviHzm5YdO formula: DateTrunc("day", [Date]) - id: nCqIz0Wiw8 formula: Sum([Max Temperature F]) - id: inode-l8GQlchbkER0Af7BOfjtNa/DATE formula: '[WEATHER/Date]' - id: inode-l8GQlchbkER0Af7BOfjtNa/MAX_TEMPERATURE_F formula: '[WEATHER/Max Temperature F]' - id: inode-l8GQlchbkER0Af7BOfjtNa/MEAN_TEMPERATURE_F formula: '[WEATHER/Mean Temperature F]' - id: inode-l8GQlchbkER0Af7BOfjtNa/MIN_TEMPERATURE_F formula: '[WEATHER/Min Temperature F]' yAxis: columnIds: - nCqIz0Wiw8 xAxis: columnId: yviHzm5YdO pages: - id: SE7diV3TMX name: Page 1 config: margin: 50 pageHeight: 1123 pageWidth: 794 layout: | ``` Report layouts use a pixel system, instead of a grid system like workbooks. Instead of using `gridColumn` and `gridRow` attributes to position elements, report layouts use `x` and `y` coordinates. For more information on workbook layout, see [Customize the layout of a workbook in code representation](/docs/customize-the-layout-of-a-workbook-in-code-representation). ## Representing page layout In this example representation, the element layout is defined in the `layout` field, and margin and page size are defined in the `config` field. #### Layout and config representation ```yaml config: margin: 50 pageHeight: 1123 pageWidth: 794 layout: | ``` The `layout` field contains one `` element per report page. The `id` attribute of `` must match the `id` of the corresponding page in the `contents.pages` array. Inside ``, each `` entry places one element on that page — the `elementId` attribute must match the `id` of the corresponding element in the `contents.elements` array. Each `` entry contains information about the element's position and size on the page: * **Position**: `x` and `y` pixel values set the position of the element's top-left corner. The `x` and `y` positions are relative to the top-left corner of the page (`0,0`), excluding the margins. * **Size**: `width` and `height` attributes set the element's size. ## Representing page size and margins The `config` field defines report-level page setup. It contains the following values, all measured in pixels: | Field | Description | | ------------ | -------------------------------------------------------------------------- | | `margin` | The page margin, which insets the content area from the edges of the page. | | `pageHeight` | The height of the report page. | | `pageWidth` | The width of the report page. |