Manage UI extension layout

By default, UI extension components will arrange themselves based on their content, order, and any layout-related props included with the component, such as the width prop for images. But HubSpot also provides the following set of components for further configuring your extension’s layout:

These components are based on CSS flexbox layout, and act as wrappers for other components. For full examples of using Flex and Box, check out HubSpot’s Managing layout: Flex and Box sample project.

AutoGrid

The AutoGrid component arranges components into columns based on available space and specified column width restraints. Includes two modes: fixed column sizing (default), and flexible column sizing. For both modes, the layout will be responsive automatically, whether you’re using it in an app card, app home page, or app settings page.

import { AutoGrid, Tile } from "@hubspot/ui-extensions";

<AutoGrid columnWidth={250} gap="small">
  <Tile>Item 1</Tile>
  <Tile>Item 2</Tile>
  <Tile>Item 3</Tile>
  <Tile>Item 4</Tile>
</AutoGrid>;

Prop	Type	Description
`columnWidth`	Number	Sets width of each column in pixels. When `flexible` is `true`, acts as minimum width before expanding.
`flexible`	Boolean	When `false`, columns have exact `columnWidth`. When `true`, columns expand equally to fill available space with `columnWidth` as the minimum. Default is `false`.
`gap`	`flush` (default) \| `'xs'`, `'extra-small'` \| `'sm'`, `'small'` \| `'med'`, `'medium'` \| `lg`, `large` \| `xl`, `extra-large`	Sets spacing between grid items.

Flex

The Flex component renders an empty div container set to display=flex. When wrapped around other components, this enables those child components to be arranged using props. Below are the available Flex props. To review all Flex prop definitions, check out the components reference guide.

Prop	Values	Description
`align`	`start` \| `center` \| `baseline` \| `end` \| `stretch` (default)	Distributes components along the cross-axis using the available free space.
`alignSelf`	`start` \| `center` \| `baseline` \| `end` \| `stretch`	Distributes a child component along the cross-axis using the available free space. Use this prop for nested child `Flex` and `Box` components to align them differently from other child components in the `Flex` group.
`direction`	`row` (default) \| `column`	Arranges components horizontally or vertically by setting the main axis.
`gap`	`flush` (default) \| `extra-small` \| `small` \| `medium` \| `large` \| `extra-large`	Sets the spacing between components.
`justify`	`start` (default) \| `center` \| `end` \| `around` \| `between`	Distributes components along the main axis using the available free space.
`wrap`	`wrap` \| `nowrap`	Whether components will wrap instead of trying to fit on one line.

Review the examples below to see how the Flex component can be used to arrange components in various ways.

Horizontal layout

To arrange components horizontally, set direction to row. Then, use justify to configure the horizontal distribution. By default, components will stretch across the container if justify is not specified. To arrange components horizontally and evenly spaced:

<Flex direction={"row"} justify={"between"}>
  <Tile>Tile 1</Tile>
  <Tile>Tile 2</Tile>
  <Tile>Tile 3</Tile>
</Flex>;

To arrange components horizontally, evenly spaced, and with equal spacing on the left and right margins:

<Flex direction={"row"} justify={"around"}>
  <Tile>Tile 1</Tile>
  <Tile>Tile 2</Tile>
  <Tile>Tile 3</Tile>
</Flex>;

To arrange components horizontally at the end of the extension container:

<Flex direction={"row"} justify={"end"}>
  <Tile>Tile 1</Tile>
  <Tile>Tile 2</Tile>
  <Tile>Tile 3</Tile>
</Flex>;

To arrange components horizontally at the center of the extension container:

ui-extensions-layout-tile-justify-center

<Flex direction={"row"} justify={"center"}>
  <Tile>Tile 1</Tile>
  <Tile>Tile 2</Tile>
  <Tile>Tile 3</Tile>
</Flex>;

To arrange components horizontally at the start of the extension container:

<Flex direction={"row"} justify={"start"}>
  <Tile>Tile 1</Tile>
  <Tile>Tile 2</Tile>
  <Tile>Tile 3</Tile>
</Flex>;

Wrap

By default, components in a row will be arranged on one line when possible. Use the wrap prop to wrap components onto new lines when needed.

<Flex direction={"row"} justify={"between"} wrap={"wrap"} gap={"medium"}>
  <Tile>One</Tile>
  <Tile>Two</Tile>
  <Tile>Three</Tile>
  <Tile>Four</Tile>
  <Tile>Five</Tile>
  <Tile>Six</Tile>
  <Tile>Seven</Tile>
  <Tile>Eight</Tile>
</Flex>;

Vertical layout

To arrange components vertically, set direction to column, then use the align prop to distribute them. By default, components will stretch across the extension container width when align is not specified. To arrange components vertically at the start of the extension container:

ui-extensions-layout-tile-column-align-start

<Flex direction={"column"} align={"start"}>
  <Tile>Tile 1</Tile>
  <Tile>Tile 2</Tile>
  <Tile>Tile 3</Tile>
</Flex>;

To arrange components vertically at the center of the extension container:

ui-extensions-layout-tile-column-align-center

<Flex direction={"column"} align={"center"}>
  <Tile>Tile 1</Tile>
  <Tile>Tile 2</Tile>
  <Tile>Tile 3</Tile>
</Flex>;

To arrange components vertically at the end of the extension container:

ui-extensions-layout-tile-column-align-end

<Flex direction={"column"} align={"end"}>
  <Tile>Tile 1</Tile>
  <Tile>Tile 2</Tile>
  <Tile>Tile 3</Tile>
</Flex>;

Spacing

In the Flex component, you can use the gap prop to apply even spacing between the tiles. This prop will apply spacing equally for both row and column directions.

<Flex direction={"row"} justify={"start"} gap={"flush" | "extra-small" | "small" | "medium" | "large" | "extra-large"}>
  <Tile>Tile 1</Tile>
  <Tile>Tile 2</Tile>
  <Tile>Tile 3</Tile>
</Flex>;

Using Flex in Flex

You can wrap child Flex components with Flex to set more specific rules for individual components. A child Flex component will not inherit props specified in the parent Flex component, so you’ll need to repeat any props you’ve previously defined to maintain them.

<Flex direction={"row"} justify={"end"} wrap={"wrap"} gap={"small"}>
  <Tile>Left</Tile>
  <Tile>Right</Tile>
  <Flex direction={"column"}>
    <Tile>Bottom</Tile>
  </Flex>
</Flex>;

Box

When wrapping components with Flex, you can further configure individual component layout by wrapping a child of Flex in a Box component. This component supports the following props. To review all Box prop definitions, check out the components reference guide.

Prop	Values	Description
`alignSelf`	`start` \| `center` \| `baseline` \| `end` \| `stretch`	Distributes a child component along the cross-axis using the available free space. Use this prop for nested child `Flex` and `Box` components to align them differently from other child components in the `Flex` group.
`flex`	`initial` (default) \| `auto` \| `none` \| number	Distributes components based on the available empty space around them.

Use the flex prop in a Box component to assign any extra spacing to components using either a default value (e.g. auto) or a specific number. When using a number, the components will be distributed based on the ratio of their assigned numbers. For example, the four tiles below take up an increasing amount of space based on their flex values.

<Flex direction={"row"} justify={"start"} gap={"small"}>
  <Box flex={1}>
    <Tile>flex = 1</Tile>
  </Box>
  <Box flex={2}>
    <Tile>flex = 2</Tile>
  </Box>
  <Box flex={3}>
    <Tile>flex = 3</Tile>
  </Box>
  <Box flex={4}>
    <Tile>flex = 4</Tile>
  </Box>
</Flex>;

When using Box, you only need to wrap components that you want to adjust. For example, if you wrap one component in a Box with a flex value, only that one component will have its width adjusted based on the available empty space.

<Flex direction={"row"} justify={"start"} gap={"small"}>
  <Box flex={1}>
    <Tile>Tile 1</Tile>
  </Box>
  <Tile>Tile 2</Tile>
  <Tile>Tile 3</Tile>
</Flex>;

When setting a flex value for only one Box, you can use any number. This is because any number on its own will result in all available space being assigned to that one component.

You can also use the alignSelf prop to override alignment rules for individual Box components.

<Flex direction={"column"} gap={"small"} align={"start"}>
  <Box alignSelf={"end"}>
    <Tile>Top right</Tile>
  </Box>
  <Box alignSelf={"center"}>
    <Tile>Middle</Tile>
  </Box>
  <Tile>Bottom left</Tile>
</Flex>;

Inline

Use the Inline component to organize child components into a horizontal row.

import { Inline, Input, Select, Button, hubspot } from "@hubspot/ui-extensions";

hubspot.extend(() => <Extension />);

function Extension() {
  return (
    <>
      <Inline gap="small" align="end" justify="start">
        <Input label="Search" placeholder="Search contacts..." name="search" />
        <Select
          label="Status"
          options={[
            { label: "All", value: "all" },
            { label: "Active", value: "active" },
            { label: "Inactive", value: "inactive" },
          ]}
          name="status"
        />
        <Select
          label="Type"
          options={[
            { label: "All Types", value: "all" },
            { label: "Leads", value: "leads" },
            { label: "Customers", value: "customers" },
          ]}
          name="type"
        />
        <Button variant="primary">Search</Button>
      </Inline>
    </>
  );
}

Prop	Type	Description
`align`	`'start'` \| `'center'` \| `'end'` \| `'baseline'` \| `'stretch'` (default)	Distributes components along the cross-axis using the available free space.
`gap`	`'flush'` (default) \| `'extra-small'`, `'xs'` \| `'small'`, `'sm'` \| `'medium'`, `'md'` \| `'large'`, `'lg'` \| `'extra-large'`, `'xl'`	The amount of spacing between components.
`justify`	`'start'` (default) \| `'center'` \| `'end'` \| `'around'` \| `'between'`	Distributes components along the main axis using the available free space.

​AutoGrid

​Flex

​Horizontal layout

​Wrap

​Vertical layout

​Spacing

​Using Flex in Flex

​Box

​Inline

AutoGrid

Flex

Horizontal layout

Wrap

Vertical layout

Spacing

Using Flex in Flex

Box

Inline