Stack

Stack is a layout component that makes it easy to stack elements together in any direction (horizontally, vertically, and even along depth). By default, it renders a Box element.

Import#

Pearl UI exports 4 stack-related components:

Stack: Used to stack elements in the horizontal or vertical direction. Particularly useful when you need to dynamically control the stacking direction.
HStack: Used to stack elements in the horizontal direction.
VStack: Used to stack elements in the vertical direction.
ZStack: Used to stack elements on top of each other.

import { Stack, HStack, VStack, ZStack } from "pearl-ui";

Usage#

<Stack direction="horizontal" spacing="m">  <Box w={20} h={20} backgroundColor="primary.500" />  <Box w={20} h={20} backgroundColor="primary.500" />  <Box w={20} h={20} backgroundColor="primary.500" />  <Box w={20} h={20} backgroundColor="primary.500" /></Stack>

Horizontal Stacking#

<HStack spacing="s">  <Box w={20} h={20} backgroundColor="secondary.500" />  <Box w={20} h={20} backgroundColor="secondary.500" /></HStack>
<Stack direction="horizontal" spacing="m">  <Box w={20} h={20} backgroundColor="primary.500" />  <Box w={20} h={20} backgroundColor="primary.500" /></Stack>

Vertical Stacking#

<VStack spacing="s">  <Box w={20} h={20} backgroundColor="secondary.500" />  <Box w={20} h={20} backgroundColor="secondary.500" /></VStack>
<Stack direction="vertical" spacing="m">  <Box w={20} h={20} backgroundColor="primary.500" />  <Box w={20} h={20} backgroundColor="primary.500" /></Stack>

Depth Stacking#

By default, the elements are stacked in an increasing order of the provided elements. For instance, in the example below, the second Box will be stacked on top of the first Box. This order can be reversed using the reversed prop expected by ZStack.

<ZStack>  <Box w={20} h={20} backgroundColor="secondary.500" />  <Box w={20} h={20} backgroundColor="secondary.500" />  <Box w={20} h={20} backgroundColor="secondary.500" /></ZStack>

In some cases, you might need to explicitly specify the zIndex of one of the stacked elements. This can be easily achieved as follows:

<ZStack>  <Box w={20} h={20} backgroundColor="secondary.500" />  <Box w={20} h={20} zIndex="docked" backgroundColor="secondary.500" />  <Box w={20} h={20} backgroundColor="secondary.500" /></ZStack>

Responsive direction#

You can control the direction of the Stack component responsively to change the stack direction based on the screen size.

<Stack direction={{ phone: "vertical", tablet: "horizontal" }} spacing="s">  <Box w={20} h={20} backgroundColor="secondary.500" />  <Box w={20} h={20} backgroundColor="secondary.500" /></Stack>

Adding dividers#

In some scenarios, you may want to add dividers between the stacked elements. This can be done by passing the Divider(or any custom React element) to the divider prop.

import { Divider } from 'pearl-ui'
<HStack spacing="s" divider={<Divider />}>  <Box w={20} h={20} backgroundColor="primary.500" />  <Box w={20} h={20} backgroundColor="primary.500" /></HStack>
<VStack spacing="s" divider={<Divider bg="cyan" />}>  <Box w={20} h={20} backgroundColor="secondary.500" />  <Box w={20} h={20} backgroundColor="secondary.500" /></VStack>

Example#

Light
Dark

Embed not loading? Click here

Stack Props#

Supported style props#

Stack composes Box so you can pass all Box related props to it.

Additional props#

Name	Required	Type	Description
`direction`	true	"horizontal" \| "vertical"	The direction to stack the items.
`spacing`	false	PearlTheme["spacing"]	The spacing between the elements.
`divider`	false	React.ReactElement	If specified, each stack item will show the provided divider.

HStack Props#

Supported style props#

HStack composes Box so you can pass all Box related props to it.

Additional props#

Name	Required	Type	Default	Description
`spacing`	false	PearlTheme["spacing"]		The spacing between the elements.
`divider`	false	React.ReactElement		If specified, each stack item will show the provided divider.

VStack Props#

Supported style props#

VStack composes Box so you can pass all Box related props to it.

Additional props#

Name	Required	Type	Default	Description
`spacing`	false	PearlTheme["spacing"]		The spacing between the elements.
`divider`	false	React.ReactElement		If specified, each stack item will show the provided divider.

ZStack Props#

Supported style props#

ZStack composes Box so you can pass all Box related props to it.

Additional props#

Name	Required	Type	Default	Description
`reversed`	false	boolean	`false`	Specifies the stacking order of the provided elements.