ui/Layout

A convenient tool for laying-out content using Layout, Cell, Row, and Column.

Layout is a powerful and versatile tool used for arranging content on the screen. On a conceptual level, it mixes the best parts of HTML tables with the best parts of HTML framesets, both of which were largely abandoned for their drawbacks, ignoring their strengths. A Layout is simply a container for Cell, the only "legal" child. Conversely, Cell may only be used in a Layout. Cells in a Layout can either be positioned next to each other (horizontally) or above/below each other (vertically) in what we refer to as a ui/Layoutui/Layout.Row or ui/Layoutui/Layout.Column, respectively.

The Row and Column layout presets describe the direction of layout for their children. This can sometimes cause confusion. A Row of children naturally forms a layout whose children can have the appearance of columns. To keep things clear, think about the layout rather than what the children themselves represent.

Layout is an implementation of flex-box, but with built-in rails, properties, and features to help avoid common problems with flex-box; things like content overflowing, sizing quirks, and positioning problems regarding content of unknown or undefined dimension.

The following scenarios are some common cases where Layout can truly help out. A quality of Cell you'll see below is that when a Cell has no defined size, it automatically sizes to fill any remaining space in the Layout. If there are multiple auto-sizing Cell components, they share the space, subdividing it equally among themselves. It's great to leverage this and only apply sizes to Cells which must have defined sizes. shrink is one of the ways you can impose size guidelines on a Cell. It automatically fits the size of the Cell to the size of its content.

A row of cells where the last one should always attach to the right side, regardless of the size of the main "content" cell:

┌───────┬─┐
│Main   │R│
└───────┴─┘

<Row>
	<Cell>Main Content</Cell>
	<Cell shrink>Right Side</Cell>
</Row>

A "two-column" layout with equal sized cells using Row:

┌────┬────┐
│L   │R   │
└────┴────┘

<Row style={{height: '100%'}}>
	<Cell>Left Column</Cell>
	<Cell>Right Column</Cell>
</Row>

Remember: The cells of the Row are the columns in our layout. It's likely that in a complex layout Column would be used inside the left and right cells to arrange the components, as in the example below.

A full-height sidebar with a header and body to the right:

┌──┬──────┐
│S │HEADER│
│  ├──────┤
│  │Body  │
│  │      │
└──┴──────┘

<Row style={{height: '100%'}}>
	<Cell size="20%">Sidebar</Cell>
	<Cell>
		<Column>
			<Cell size={90} component="header">
				<h1>HEADER</h1>
			</Cell>
			<Cell>
				<p>Body area</p>
			</Cell>
		</Column>
	</Cell>
</Row>

Note: Here, we've set the height of Row so it fills the height of the screen, allowing the Sidebar Cell and content Cell to stretch from the top to the bottom. We've also leveraged the component prop on the header cell, which tells Cell to render itself as a "header" HTML tag rather than its usual "div" tag.

The example below produces a layout like the following:

┌─┬─────┬─┐
│o│Item │o│
└─┴─────┴─┘

You'll notice the use of some special classes in the example: "debug layout". Adding these on any element in your DOM hierarchy will enable borders in Layout and Cell to help visualize what is happening in the layout. They automatically change color the deeper in the stack they go.

Loading Live Preview

Import Usage

import Layout from '@enact/ui/Layout';

Members

Layout   Component

A container for Cells.

A stateless component that acts as a containing area for ui/Layoutui/Layout.Cell to be positioned in a row or a column (horizontally or vertically, respectively. It supports an ui/Layoutui/Layout.LayoutBase.orientation property for laying-out its contents (Cells) in an organized, readable way.

Example:

import Input from '@enact/moonstone/Input';
import css from './LayoutExample.less';
...
<fieldset>
	<Layout align="center">
		<Cell component="label" size="40%" className={css.label} shrink>First Name</Cell>
		<Cell component={Input} placeholder="First" className={css.input} />
	</Layout>
	<Layout align="center">
		<Cell component="label" size="40%" className={css.label} shrink>Last Name</Cell>
		<Cell component={Input} placeholder="Last" className={css.input} />
	</Layout>
</fieldset>

Import Usage

import Layout from '@enact/ui/Layout';

Extends: ui/Layoutui/Layout.LayoutBase
Wrapped with: ui/ForwardRefui/ForwardRef.ForwardRef

Cell   Component

A stateless component that provides a space for your content in a ui/Layoutui/Layout.Layout.

Import Usage

import {Cell} from '@enact/ui/Layout';

Extends: ui/Layoutui/Layout.CellBase
Wrapped with: ui/Layoutui/Layout.CellDecorator

CellBase   Component

A stateless component that provides a space for your content in a ui/Layoutui/Layout.Layout, without ui/Layoutui/Layout.CellDecorator applied.

Import Usage

import {CellBase} from '@enact/ui/Layout';

Properties

align

String

The alignment of Cell.

Aligns this Cell vertically in the case of a horizontal layout or horizontally in the case of a vertical layout. "start", "center" and "end" are the most commonly used, although all values of align-self are supported. "start" refers to the top in a horizontal layout, and left in a vertical LTR layout "end" refers to the bottom in a horizontal layout, and right in a vertical LTR layout "start" and "end" reverse places when in a vertical layout in a RTL locale.

---

children

Any

Any valid /docs/developer-guide/glossary/#node/docs/developer-guide/glossary/#node that should be positioned in this Cell.

---

component

StringComponent

The type of component to use to render as the Cell. May be a DOM node name (e.g 'div', 'span', etc.) or a custom component.

Default: 'div'

---

componentCss

Object

Customizes Cell together with component prop.

When using ui/Layoutui/Layout.Cell, the componentCss prop is passed to the rendered component as css.

---

componentRef

ObjectFunction

Called with a reference to the root component.

When using ui/Layoutui/Layout.Cell, the ref prop is forwarded to the rendered component as componentRef.

---

grow

Boolean

Sizes Cell to its container.

A growable cell will expand to its maximum size, according to the remaining space of the container. This is used when you want to grow the size of this Cell so that it fills the container. See the ui/Layoutui/Layout.CellBase.size property for more details.

When combined with ui/Layoutui/Layout.CellBase.shrink, shrink prop takes precedence over grow prop and grow prop is simply ignored.

---

shrink

Boolean

Sizes Cell to its contents.

A shrinkable cell will contract to its minimum size, according to the dimensions of its contents. This is used when you want the size of this Cell's content to influence the dimensions of this cell. shrink will not allow the contents of the Layout to be pushed beyond its boundaries (overflowing). See the ui/Layoutui/Layout.CellBase.size property for more details.

Default: false

---

size

StringNumber

Sets the desired size of the Cell using any valid CSS measurement value.

When used in conjunction with ui/Layoutui/Layout.CellBase.shrink, the size will be the maximum size, shrinking as necessary, to fit the content.

When used in conjunction with ui/Layoutui/Layout.CellBase.grow, the size will be the minimum size, growing as necessary, to fit the container.

E.g.

• size="400px" -> cell will be 400px, regardless of the dimensions of your content

• size="400px" shrink -> cell will be 400px if your content is greater than 400px, and will match your contents size if it's smaller

• size="400px" grow -> cell will be 400px if the container has no remaining space. Cell can grow larger than size to fill the container if there is remaining space in the container.

This accepts any valid CSS measurement value string. If a numeric value is used, it will be treated as a pixel value and converted to a ui/resolutionui/resolution.unit based on the rules of ui/resolutionui/resolution.

CellDecorator   Higher-Order Component

Applies Cell behaviors.

Import Usage

import {CellDecorator} from '@enact/ui/Layout';

Includes: ui/ForwardRefui/ForwardRef.ForwardRef

Column   Component

Shorthand for <Layout orientation="vertical">, which positions its ui/Layoutui/Layout.Cell vertically.

┌────┐
├────┤
├────┤
├────┤
└────┘

Import Usage

import {Column} from '@enact/ui/Layout';

Extends: ui/Layoutui/Layout.Layout
Wrapped with: ui/ForwardRefui/ForwardRef.ForwardRef

LayoutBase   Component

A container for Cells.

A stateless component that acts as a containing area for ui/Layoutui/Layout.Cell to be positioned in a row or a column (horizontally or vertically, respectively. It supports an ui/Layoutui/Layout.LayoutBase.orientation property for laying-out its contents (Cells) in an organized, readable way.

Example:

import Input from '@enact/moonstone/Input';
import css from './LayoutExample.less';
...
<fieldset>
	<Layout align="center">
		<Cell component="label" size="40%" className={css.label} shrink>First Name</Cell>
		<Cell component={Input} placeholder="First" className={css.input} />
	</Layout>
	<Layout align="center">
		<Cell component="label" size="40%" className={css.label} shrink>Last Name</Cell>
		<Cell component={Input} placeholder="Last" className={css.input} />
	</Layout>
</fieldset>

Import Usage

import {LayoutBase} from '@enact/ui/Layout';

Properties

align

String

The alignment of children.

Aligns the children ui/Layoutui/Layout.Cell vertically in the case of a horizontal layout or horizontally in the case of a vertical layout. "start", "center" and "end" are the most commonly used, although all values of align-items are supported. "start" refers to the top in a horizontal layout, and left in a vertical LTR layout "end" refers to the bottom in a horizontal layout, and right in a vertical LTR layout "start" and "end" reverse places when in a vertical layout in a RTL locale. This includes support shorthand for combining align-items and justify-content into a single property, separated by a space, in that order. This allows you to specify both the horizontal and vertical alignment in one property, separated by a space.

For example, align="center space-between" means align-items: center and justify-content: space-between for each. justify-content property can be used to align the Cells on the main axis and adjust gaps among the Cells. To declare the justify-content property only, just add a heading space for align prop string like align=" space-between". The default value for align-items is stretch. It can be also used for align prop like align="stretch space-between". All values of justify-content are supported, like start, end, center, space-between, space-around, and space-evenly.

<Layout align="center space-around">
    <Cell>Left Column</Cell>
    <Cell>Right Column</Cell>
</Layout>

<Layout align=" space-between">
    <Cell>Left Column</Cell>
    <Cell>Right Column</Cell>
</Layout>

---

children

CellArray(Cell)

Only ui/Layoutui/Layout.Cell components are supported as children.

---

component

StringComponent

The type of component to use to render as the Layout. May be a DOM node name (e.g 'div', 'span', etc.) or a custom component.

Default: 'div'

---

componentRef

ObjectFunction

Called with a reference to the root component.

When using ui/Layoutui/Layout.Layout, the ref prop is forwarded to this component as componentRef.

---

inline

Boolean

Allows this Layout to have following siblings drawn on the same line as itself instead of carving out the entire horizontal space for itself.

Default: false

---

orientation

String

The orientation of the Layout, i.e. how the children ui/Layoutui/Layout.Cell are positioned on the screen. Must be either 'horizontal' or 'vertical'.

Default: 'horizontal'

---

wrap

BooleanString

Sets the Layout's flex-wrap values.

Determines how a Layout handles its cells if there are more than fit in the available space. This works like a normal Boolean prop, but also accepts strings for customization beyond the basic on/off support. In addition to true and false, the following strings are supported: 'wrap', 'nowrap', 'reverse'. 'reverse' performs standard line wrapping but additional lines are placed above/before the preceding line instead of below/after.

LayoutDecorator   Higher-Order Component

Applies Layout behaviors.

Import Usage

import {LayoutDecorator} from '@enact/ui/Layout';

Includes: ui/ForwardRefui/ForwardRef.ForwardRef

Row   Component

Shorthand for <Layout orientation="horizontal">, which positions its ui/Layoutui/Layout.Cell horizontally.

┌─┬─┬─┬─┐
│ │ │ │ │
└─┴─┴─┴─┘

Import Usage

import {Row} from '@enact/ui/Layout';

Extends: ui/Layoutui/Layout.Layout
Wrapped with: ui/ForwardRefui/ForwardRef.ForwardRef