Stack

Source

The Stack component is a versatile layout tool that allows you to easily stack elements in various directions - horizontally, vertically, or along the depth axis. By default, it renders a Box element, providing a flexible and consistent way to manage your layout.

Import#

Pearl UI provides four stack-related components to cater to different layout needs:

Stack: This is a flexible component that can stack elements either horizontally or vertically. It's especially useful when you need to dynamically control the stacking direction.
HStack: This component is designed to stack elements horizontally.
VStack: Use this component when you need to stack elements vertically.
ZStack: This component stacks elements on top of each other, providing a way to manage depth in your layout.

You can import these components from Pearl UI like so:

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

How to Use Stack Components#

Here's a basic example of how to use the Stack component:

<Stack direction="horizontal" spacing="4">  <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>

Stacking Horizontally#

You can use either the HStack component or the Stack component with the direction prop set to "horizontal" to stack elements horizontally. Here's how:

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

Stacking Vertically#

To stack elements vertically, you can use the VStack component or the Stack component with the direction prop set to "vertical". Here's an example:

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

Stacking Along the Depth Axis#

The ZStack component allows you to stack elements along the depth axis. By default, the elements are stacked in the order they are provided. For instance, in the example below, the second Box will be stacked on top of the first Box. You can reverse this order using the reversed prop.

<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 Stacking#

The Stack component allows you to responsively control the stack direction based on the screen size. Here's an example:

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

Adding Dividers Between Elements#

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="2" divider={<Divider />}>  <Box w={20} h={20} backgroundColor="primary.500" />  <Box w={20} h={20} backgroundColor="primary.500" /></HStack>
<VStack spacing="2" divider={<Divider bgColor="cyan" />}>  <Box w={20} h={20} backgroundColor="secondary.500" />  <Box w={20} h={20} backgroundColor="secondary.500" /></VStack>

Examples#

Here are some examples of how you can use the Stack components in your project:

Embed not loading? Click here

Stack Component Properties#

Supported Style Properties#

The Stack component composes the Box component, so you can pass all Box related props to it.

Additional Properties#

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

HStack Component Properties#

Supported Style Properties#

The HStack component composes the Box component, so you can pass all Box related props to it.

Additional Properties#

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

VStack Component Properties#

Supported Style Properties#

The VStack component composes the Box component, so you can pass all Box related props to it.

Additional Properties#

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

ZStack Component Properties#

Supported Style Properties#

The ZStack component composes the Box component, so you can pass all Box related props to it.

Additional Properties#

Name	Required	Type	Default	Description
`spacing`	No	PearlTheme["spacing"]	`2`	The spacing between the elements.
`reversed`	No	boolean	`false`	Specifies the stacking order of the provided elements.