# grid

## Overview

The `grid` UI component gives developers more control over the layout of UI components in a view. This is useful when there is a need to customize the width of UI components respective to other components on the view (where previously [`columns`](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/columns) kept each component’s width equal). `grid` could also be used to layout components in a way that is similar to layout to icons on a phone’s homescreen. Another use case is to keep more content visible on the screen, where previously [`column`](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/columns/column) content overflowed and became scrollable.

{% hint style="info" %}
**Version compatibility**

`grid` was introduced in version **4.85.0** of the JourneyApps Runtime.
{% endhint %}

A `grid` contains `cell`s to specify the size and position of UI components:

{% content-ref url="grid/cell" %}
[cell](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/grid/cell)
{% endcontent-ref %}

### Basic Example

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2FiEfDrdCt9jelirBnzs9p%2Fgrid-example.jpeg?alt=media\&token=bb0775fe-47bf-447f-9bfb-c8bed8d78340)

{% code title="main.view\.xml" %}

```xml
<grid>
    <cell>
        <heading>Cell 1</heading>
        <display-image src="images/example-corp-main-view-image-001.png" />
    </cell>
    <cell>
        <heading>Cell 2</heading>
        <text-input label="First name" bind="first_name" required="false" />
    </cell>
    <cell>
        <heading>Cell 3</heading>
        <capture-photo label="Photo of Person" bind="photo" source="any" resolution="small" downloadable="true" />
    </cell>
    <cell column-span="2">
        <heading>Cell 4</heading>
        <text-input label="First name" placeholder="Enter first name" bind="first_name" required="false" />
        <button label="Submit" icon="fa-arrow-right" icon-position="right" />
    </cell>
    <cell>
        <heading>Cell 5</heading>
        <object-dropdown label="Country of residence" placeholder="Select a country" query="countries" bind="selected_country" required="false" />
    </cell>
    <cell column-span="2">
        <heading>Cell 6</heading>
        <display-coordinates id="current-location" label="Current location" bind="current_location" allow-zoom="true" allow-dragging="true">
            <marker label="You are here" bind="marker" icon="fa-home" />
        </display-coordinates>
    </cell>
</grid>
```

{% endcode %}

Have a look at some additional examples here:

{% content-ref url="grid/grid-examples" %}
[grid-examples](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/grid/grid-examples)
{% endcontent-ref %}

### Limitations

* Nesting a `grid` inside an `object-repeat` is not currently supported.

## Standard Attributes

None

## Advanced Attributes

### `column-count`

**Optional**

**Type**: `integer`

**Default**: Is automatically determined based on the [minimum allowed column width](#column-min-width).

Specify the number of columns that the `grid` will generate.

{% hint style="info" %}
**Note**:&#x20;

* If `column-count` has been specified and the columns do not fit inside the screen (such as on small devices) then the grid will become horizontally scrollable.&#x20;
* If `column-count` has not been specified, i.e. the column count is automatically determined, the grid component will try and reduce the number of columns to adhere to the [minimum allowed column width](#column-min-width) as the screen size is reduced.
  {% endhint %}

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2FcsZjccPU2icbdJh37uvV%2Fgrid-example-column-count.png?alt=media\&token=809b417f-9fd2-4265-9454-89ace18c6d3c)

{% code title="main.view\.xml" %}

```xml
<grid column-count="3" >
    <cell>
        <text-input label="First name" bind="first_name" required="false" />
        <button label="Button" />
    </cell>
</grid>
```

{% endcode %}

### `column-min-width`

**Optional**

**Type**: `integer`

**Default**: 250 px

Specify the minimum allowed width (in pixels) for the `grid`’s columns.

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2FuXZ0BYRNl8uZKSymmPCZ%2Fgrid-example-column-min-width.png?alt=media\&token=fd658155-da14-4443-81e8-dcfc9590cd1c)

{% code title="main.view\.xml" %}

```xml
<grid column-min-width="1000" >
    <cell>
        <text-input label="First name" bind="first_name" required="false" />
        <button label="Button" />
    </cell>
</grid>
```

{% endcode %}

### `column-order`

{% hint style="info" %}
**Version compatibility**

`column-order` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `left-to-right`| `right-to-left`

**Default**: `left-to-right`

Specify the order of the grid's columns.

{% code title="main.view\.xml" %}

```xml
<info>column-order="left-to-right"</info>
<grid column-order="left-to-right" column-count="4">
    <cell>
        <heading>Cell 1</heading>
    </cell>
    <cell>
        <heading>Cell 2</heading>
    </cell>
    <cell>
        <heading>Cell 3</heading>
    </cell>
    <cell>
        <heading>Cell 4</heading>
    </cell>
</grid>

<info>column-order="right-to-left"</info>
<grid column-order="right-to-left" column-count="4">
    <cell>
        <heading>Cell 1</heading>
    </cell>
    <cell>
        <heading>Cell 2</heading>
    </cell>
    <cell>
        <heading>Cell 3</heading>
    </cell>
    <cell>
        <heading>Cell 4</heading>
    </cell>
</grid>
```

{% endcode %}

<figure><img src="https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fr1L80NGPvrrMmN3jmrPO%2Fimage.png?alt=media&#x26;token=1aeff00d-96de-489b-b0d1-4294ea28574f" alt=""><figcaption></figcaption></figure>

### `show-if` and `hide-if`

{% content-ref url="../xml-fields/show-if" %}
[show-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/show-if)
{% endcontent-ref %}

{% content-ref url="../xml-fields/hide-if" %}
[hide-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/hide-if)
{% endcontent-ref %}

## Component Methods

None


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/grid.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.