> For the complete documentation index, see [llms.txt](https://smartui-docs.pixelperfectstudio.mx/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://smartui-docs.pixelperfectstudio.mx/framework-addons/grid-layout.md). # Grid Layout SmartUI Grid Layout Behavior operation and ACEs.

Grid Layout is an excellent option to arrange and present your components in a scene within a grid-like disposition. The component offers two operation modes: a **layouter** for static objects, and **renderer** for dynamic object rendering. It provides sufficient flexibility to handle multiple different objects per cell, opening the door to create really complex layouts and interactions, in combination with the rest of the elements of the SmartUI framework. It also inherits its features directly from the

[Container](/framework-addons/container-behavior.md) component, and provides the same navigation capabilities. {% hint style="success" %} **Rows and columns can have different width and height****,** set the properties: **Cols Width**, and **Rows Height**. See [#changing-columns-and-rows-size](#changing-columns-and-rows-size "mention") {% endhint %}

Download

## Properties | **Property** | **Description** | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Enabled` | Enables or Disables the Grid-Layout and all its children. | | `Index` | Index of the Grid-Layout within layout. Used for focusing the elements in the sequence order. | | `Invisible Component` | Turns the component opacity to 0 while rendering it to allow invisible interactions. | | `Focusable` | Marks if the component can have the focus. | | `Automatic-Color` | Enables the component to darken a bit when its state is Disabled or when it's focused. Auto-Color is meant to provide a quick identification of the component state. For more specialized customizations, use the component events and disable this check. | | `Name` | Unique name string for identifying the selected Grid-Layout | | `Operation Mode` | Defines whether the component behaves like a layouter, arranging objects; or as a Renderer, creating and destroying objects as per the datasource. | | `Render first` | Render columns or rows first. | | `Columns` | Number of initial columns for the Grid-Layout | | `Rows` | Number of initial rows for the Grid-Layout | | `Scale Mode` | Scale mode for the elements arranged in the Grid-layout | | `Col.Padding` | Column's padding in pixels. | | `Row.Padding` | Row's padding in pixels. | | `Cols.Width` | Array of width percentage values per column, to render the width in pixels based on the Grid-Layout width . Values must be from 0 to 1. Greater values will be normalized | | `Rows.Height` | Array of height percentage values per row, to render the height in pixels based on the Grid-Layout height . Values must be from 0 to 1. Greater values will be normalized | | `Paging` | Enables paging for all the items in the data array. Paging is only relevant in Renderer mode, otherwise it has no effect. | | `Items per Page` | Maximum number of items to render per page. Only relevant in Renderer mode. | | `Render Style` | Indicates whether the grid renders based on its current fixed size (content overflow not handled), or if it can grow horizontally or vertically after the columns or rows initial size is overflown. When growing is allowed, the cell size is taken from the 'Cols.Grow Rate' and 'Rows Grow Rate' properties. Note that if 'Render First' is set to the same render style, the grid will always grow in one direction. E.g.Render first columns, and cols.growing will cause the grid to never add rows. | | `Cols.Grow Rate` | When Renter-Style is set to columns or rows growing, this value is the width in pixels for each cell. | | `Rows Grow Rate` | When Renter-Style is set to columns or rows growing, this value is the height in pixels for each cell. | | `Cell Alignment` | Default content aligment of each cell. | ## :tv: Video Demo {% embed url="" %} ## Layouter Mode Layouter mode provides a quick arrangement of static objects in the scene. By *static*, we mean all the existing objects in the scene that are children of the Grid Layout container. *Layouter* is the default mode for the Grid Layout component. By simply linking the child objects in the scene, the Grid Layout component will automatically identify what’s in its hierarchy and the grid configuration to arrange them **instantly** after the layout is created. {% hint style="info" %} By design, **Layouter's mode** **main purpose is to quickly arrange objects in a scene** without the need to handle additional data sources, not to render dynamic data. For that purpose, see Renderer mode. {% endhint %}

Initial object arrangement in the Layout

{% hint style="warning" %} Grid Layouter will use the [Document Flow](/getting-started/quickstart/document-flow.md) determine the order of the components. **Objects are handled in a list data structure,** and their indexes are automatically mapped against the grid to render them in the correct cell." {% endhint %} Each object in the hierarchy is iterated. If the grid determines that it doesn’t use any of the SmartUI behaviors, the sequence index is omitted, and the object’s position becomes the only relevant attribute to determine the order. {% hint style="success" %} **Any world object can become a cell of the grid;** you are not restricted to using only the Smart UI behaviors. {% endhint %} After running the scene, the objects are arranged as show below:

Objects are automatically arranged in the grid

Notice how the content of each cell does not match the size of the Grid Layout object. This is because, by default, the layouter will render the objects' original size in the layout you are designing. You can change the **Scale Mode** property of the Grid Layout from **None** to either **fit** the cell size or **stretch** the content to match the cell size.

None is de default scaling mode, keeping the original size of the object.

### Changing Columns and Rows Size Grid Layout supports multiple sizes for rows and columns. To change them, set the **Cols Width** and **Rows Height** properties. The input for those attributes is a list of values between 0 and 1, where 1 represents 100% of either the width or height of the Grid Layout's size. For instance, if you have a 4x4 grid and want to add a titles row at the top, and also set the first column to contain a numeric ID, you can achieve this by keeping in mind the document flow logic to semi-arrange your objects in the layout. Your scene might look like the following to set up your Grid Layout.

Notice how the rows and columns have an approximate location, but are not quite precise, and that's perfectly fine. We are taking advantage of how the [Document Flow](/getting-started/quickstart/document-flow.md) iterates the objects in the scene. The next step is to set up the width and height sizes as follows:

{% hint style="warning" %} **The sum of the values for the rows height and columns width properties must be 1.** If the sum is above 1, the values will be normalized, and the Grid Layout component will try to fit them within its rendering area {% endhint %} According to the image, we’ve indicated that the first column is 10% of the total width of the Grid Layout. Rows will follow the same structure, so the first row will also have 10% of the Grid Layout's height.

Final component arrangement after changing the columns and rows sizes.

{% hint style="info" %} If you fail to enter a value for either a column width or a row height in their respective lists, the component **will default to an approximate even distribution of sizes for all the cells.** {% endhint %} Layouter also supports dynamic insertion of objects; nevertheless, keep in mind that objects are still treated as a list but displayed in a grid arrangement. Therefore, if you add an object to a cell, all subsequent objects will be pushed down in the list, causing the grid to recalculate their positions using the [Document Flow](/getting-started/quickstart/document-flow.md). ## Renderer Mode Renderer mode is designed to handle dynamic data and object creation based on a [#grid-renderer-configuration-file](#grid-renderer-configuration-file "mention"). The file can be imported into the Grid Layout component by calling the `Set Datasource` action, which takes a `JSON` object as input. The rendering features used by Layouter mode are still valid for Renderer mode.

Construct already provides `AJAX`, `JSON`, and file management capabilities. For this reason, the plugin considers the input throught the existing built-in plugins.

1. Use the AJAX plugin to retrieve the configuration file data.

2. When ajax succesfully retrieves the file, read the LastData attribute, parse it to a JSON object and call the Set Datasource action.

The action `Set Datasource` reads the `JSON` data, and creates a copy that is later stored in the Grid Layout component for rendering. {% hint style="warning" %} **If you change by any mean the JSON plugin data, you must then call the**** ****`Set Datasource`** action again and refresh the Grid Layout to render the information. {% endhint %} Data-change listeners attached to construct objects are not supported, primarily because construct does not have event triggers to attach these listeners to. Therefore, the data flow to the Grid Layout remains manual. ### Grid Renderer Configuration File The configuration file has two main keys in its structure: **`data`** and **`meta-data`**. Both keys have a 1-to-1 cardinality, meaning there should be the same number of entries. * **`data`** **(mandatory)** key holds an array of objects containing the information you want to flow from the Grid Layout object to each cell. * **`meta-data`** **(mandatory)** key describes how each cell should be rendered, allowing you to combine multiple different objects in the same grid. * **`default-object`** **(mandatory)** key describes the object to render by default when there is no matching record between the `data` and `meta-data` arrays. This feature is useful in scenarios where you want to render the same object for all data rows. In such cases, the **`object-list`** **key can be an empty array (****`[]`****).** * **`object-name`** **(mandatory)** key describes the world-instance object that should be created. * **`create-hierarchy`** **(mandatory)** key indicates whether the object is created alone or with all its children. * **`template-name`** **(mandatory)** is applicable only if `create-hierarchy` is set to true. The instances will use the provided hierarchy template to create the instance. * **`object-list`** **(mandatory)** key contains an array of objects. Its cardinality must be 1-to-1 with the `data`. However, you can still pass `null` values for each row. When the grid is rendering, if the `meta-data` row is either not found or null, the object to render will default to what is indicated in the `default-object` key. **Each entry in this array has the same structure as the**** ****`default-object`**** ****key.** {% code title="Renderer Config Example" lineNumbers="true" fullWidth="false" %} ```json { "data":[ {"id":1,"name":"John","phone":"+1 555 5555"}, {"id":2,"name":"Peter","phone":"+1 444 4445"}, {"id":3,"name":"Andy","phone":"+1 333 4445"}, {"id":4,"name":"Mom","phone":"+1 653 6555"} ], "meta-data":{ "default-object": { "object-name":"MyDataBox", "create-hierarchy":true, "template-name":"one" }, "object-list":[ { "object-name":"MyGenericCell", "create-hierarchy": true, "template-name":"MyTemplate" }, null, null, { "object-name":"MyGenericCell", "create-hierarchy": false, "template-name":"" } ] } } ``` {% endcode %} ### Rendering Objects Renderer mode, by default, destroys any children in the hierarchy and then takes the information from the configuration file. Objects will render automatically once the datasource is assigned. In contrast to Layouter mode, objects do not have to be children of the Grid Layout because they are created at runtime. {% hint style="warning" %} **All children attributes (x, y, width, height, etc.) are transformed** whenever the parent object changes. {% endhint %} You can customize the way you render the `data source` by adjusting any of the Grid Layout attributes.

The component supports paging and a set of ACEs (Actions, Commands, and Events) to navigate between the pages created for the data. To enable paging, set the paging attribute to `enabled` and specify the total number of items to render per page. Data flows automatically to each cell. To access it, you must use the

[Smart UI Data Listener](/framework-addons/data-listener.md) Behavior. Add the `On Render` event from the data listener, which will be triggered by the Grid Layout for each cell. Every time a cell is rendered, the information from the `data` field is passed to the data listener. To access it, use the expression `Value` followed by the name of the key you want to retrieve. {% hint style="info" %} **On Render**** is called just once per cell.** {% endhint %} {% hint style="warning" %} The [DataListener ](/framework-addons/data-listener.md)behavior must be **attached to the top-level object being rendered.** {% endhint %} Using the configuration file example, we can render the contact information of a phone list in a Grid Layout component.

The event sheet might look like below:

On Render event receives the data from the Grid Layout

Accesing the "name" field of the data being rendered.

The **MyBoxData** has a child **Text** plugin attached to it, whenever the **MyBoxData** On Render event is called, the child **Text** plugin is picked and its value is then set from the `DataListener.Value` expression. ##

Smart UI GridLayout Smart UI Grid-Layout behavior groups UI components, provides focusing abilities and default interactions to navigate within the Grid-Layout and its children components that uses Smart UI behaviors, and handles cascading Enabling/Disabling events. It also responds to pointer interactions prioritizing by zIndex. ## Actions *** ### `Set Columns Width Array` Sets the percentage of the component's width per column to render columns of different sizes. | **Parameter** | **Description** | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Weight Array` | A comma-separated list of width percentage values per column. Values must range from 0 to 1. Larger values will be normalized. Example: 0.1, 0.2, 0.2, 0.5. | ### `Set Rows Height Array` Sets the percentage of the component's height per row to render rows of different sizes. | **Parameter** | **Description** | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Weight Array` | A comma-separated list of height percentage values per row. Values must range from 0 to 1. Larger values will be normalized. Example: 0.1, 0.2, 0.2, 0.5. | ### `Set Growing Columns Width` Defines the render width in pixels when the component expands by columns. | **Parameter** | **Description** | | --------------- | ------------------------------------------------------------------------------ | | `Columns width` | Width in pixels used to render the cell when the component expands by columns. | ### `Set Growing Rows Height` Defines the render width in pixels when the component expands by rows. | **Parameter** | **Description** | | ------------- | ---------------------------------------------------------------------------- | | `Rows height` | Height in pixels used to render the cell when the component expands by rows. | ### `Set Enabled` Disable/Enable the Grid-Layout | **Parameter** | **Description** | | ------------- | ---------------- | | `Enabled` | Enabled/Disabled | ### `Set Name` Sets the name of the Grid-Layout. | **Parameter** | **Description** | | ------------- | --------------------- | | `Name` | Name of the component | ### `Set Sequence` Sets the sequence index to influence the selection of components. | **Parameter** | **Description** | | ------------- | ---------------------------------------------------------------------------------------------- | | `Index` | Sequence index value. E.g. Indexes values of 0 are processed before indexes values of 1 and 2. | ### `Set Focusable` Sets the component to be able to receive the focus | **Parameter** | **Description** | | ------------- | ------------------------------------------ | | `Focusable` | Flag to allow the component to be focused. | ### `Set Focus` Request the focus for this Grid-Layout ### `Focus First Element` Request the focus for the first interactable element of the Grid-Layout. ### `Focus Last Element` Request the focus for the last interactable element of the Grid-Layout. ### `Set Invisible Component` Turns the component opacity to 0 while rendering it to allow invisible interactions. | **Parameter** | **Description** | | --------------------- | ----------------------------------------------------------------- | | `Invisible Component` | Set if the component processed even if it's invisible: True/False | ### `Refresh` Refreshes the layout, and arranges all the children in their corresponding cells. On Layouter mode, the grid-layout will try to determine the objects position sequentially. On Renderer mode, it will read all the entries from the datasource to render them in sequence. ### `Set Datasource` Sets the JSON plugin object that will provide the information to render the grid. | **Parameter** | **Description** | | ------------- | ------------------ | | `Datasource` | JSON plugin object | ### `Set Columns` Sets the number of columns the grid will render. | **Parameter** | **Description** | | ------------- | ------------------------------- | | `Columns` | Max number of columns to render | ### `Set Rows` Sets the number of rows the grid will render. | **Parameter** | **Description** | | ------------- | ---------------------------- | | `Rows` | Max number of rows to render | ### `Set Column Padding` Sets padding between columns. | **Parameter** | **Description** | | ------------- | ---------------------- | | `Padding` | Padding size in pixels | ### `Set Row Padding` Sets padding between rows. | **Parameter** | **Description** | | ------------- | ---------------------- | | `Padding` | Padding size in pixels | ### `Set Scaling` Sets the type of scaling the grid-layout will perform over all its content. | **Parameter** | **Description** | | ------------- | --------------- | | `Mode` | Scaling mode | ### `Insert At` In Layouter mode, inserts an object in the specified column and row, displacing the following components on cell. The object is not added to the hierarchy of the grid-layout. | **Parameter** | **Description** | | ------------- | -------------------------- | | `Object` | Object instances to insert | | `Column` | Zero-index based Column | | `Row` | Zero-index based Row | ### `Set At` In Layouter mode, places an object in the specified column and row overriding the existing location and destroying the objects in the given cell. The object is not added to the hierarchy of the grid-layout. | **Parameter** | **Description** | | ------------- | -------------------------- | | `Object` | Object instances to insert | | `Column` | Zero-index based Column | | `Row` | Zero-index based Row | ### `Set Page` In Renderer mode, changes the page. Page numberes are zero-index based. | **Parameter** | **Description** | | ------------- | ----------------------------- | | `Page` | Zero-index based page number. | ### `Set Items per Page` Sets the total number of items to render per page. | **Parameter** | **Description** | | ------------- | --------------------------------------- | | `Items` | Max number of items to render per page. | ### `Next Page` Switches to the next page available. ### `Previous Page` Switches to the previous page available. ### `Set Render Style` Sets whether the grid renders based on its current fixed size, or if it can grow horizontally or vertically after the columns or rows initial size is overflown. When growing is allowed, the cell size is taken from the 'Cols.Grow Rate' and 'Rows Grow Rate' properties. Note that if 'Render First' is set to the same render style, the grid will always grow in one direction. E.g.Render first columns, and cols.growing will cause the grid to never add rows. | **Parameter** | **Description** | | ------------- | --------------- | | `Style` | Render style. | ### `Set Render First` Indicate if the grid renders columns or rows first. | **Parameter** | **Description** | | ------------- | --------------- | | `First` | Render first. | ## Conditions *** ### `Is Enabled` Returns true if the Grid-Layout is enabled ### `Is Invisible Component` Returns true if the Grid-Layout is configured as an invisible component. ### `Compare Name` Returns true if the component's name equals the parameter | **Parameter** | **Description** | | ------------- | ------------------------------------------ | | `Name` | Name to compare with the component picked. | ### `Is Focused` Returns true if the Grid-Layout has the focus ### `Has Control` True if the Grid-Layout has the control to navigate over components. ### `On Focus` Triggered when the Grid-Layout gets the focus ### `On Focus Lost` Triggered when the Grid-Layout loses focus ### `Has Next Page` Returns true if the Grid-Layout can navigate to the next page. ### `Has Prev Page` Returns true if the Grid-Layout can navigate to the previous page. ### `On Refresh` Triggered every time the Grid-Layout is rendered. For instance, when objects are added, when it gets resized, when columns or rows change, etc. ## Expressions *** ### `Name` Component name ### `Columns` Initial Columns ### `Rows` Initial Rows ### `RenderedColumns` Rendered Columns considering overflow and available grid capacity. ### `RenderedRows` Rendered Rows considering overflow and available grid capacity. ### `ColumnPadding` Column padding ### `RowPadding` Component name ### `CellHeight` Cell's height of the given coordinates (column,row) | **Parameter** | **Description** | | ------------- | ----------------------- | | `Column` | Zero-index based Column | | `Row` | Zero-index based Row | ### `CellWidth` Cell's width of the given coordinates (column,row) | **Parameter** | **Description** | | ------------- | ----------------------- | | `Column` | Zero-index based Column | | `Row` | Zero-index based Row | ### `Page` Current Page ### `MaxPages` Maximum Pages ### `PageItems` Items per Page ### `GetRowByY` Return the row by the Y coordinate | **Parameter** | **Description** | | ------------- | -------------------------------- | | `Y` | Y coordinate to get the row from | ### `GetColByX` Return the column by the X coordinate | **Parameter** | **Description** | | ------------- | ----------------------------------- | | `X` | X coordinate to get the column from | ### `GetYByRow` Return the Y-centered coorinate of the given row | **Parameter** | **Description** | | ------------- | -------------------- | | `Row` | Zero-index based Row | ### `GetXByCol` Return the X-centered coorinate of the given col | **Parameter** | **Description** | | ------------- | ----------------------- | | `col` | Zero-index based Column | **(c) Pixel Perfect Studio 2026**