Spacing

Tosui uses a multiplier-based spacing system built on a 4px base unit. This creates consistent, harmonious spacing throughout your UI.

The Base Unit

All spacing in Tosui is calculated from a single base unit:

--t-spacing-unit: 4px

When you use spacing props like p={4} or m={8}, the value is multiplied by 4px:

Multiplier	Pixels	Common Use
0	0px	No spacing
1	4px	Tight spacing, icon gaps
2	8px	Compact elements
3	12px	Small padding
4	16px	Standard padding
6	24px	Section spacing
8	32px	Large gaps
12	48px	Section breaks
16	64px	Major sections

The system supports multipliers from 0 to 32 (0px to 128px).

To change the base unit globally, override the CSS variable:

:root {
  --t-spacing-unit: 5px;
}

With 5px, p={4} becomes 20px instead of 16px. See the Customization guide for more theming options.

Padding Props

Padding adds space inside an element's border.

import { Box } from "@tosui/react";

// All sides
<Box p={4}>16px padding on all sides</Box>

// Horizontal and vertical
<Box px={6} py={3}>24px horizontal, 12px vertical</Box>

// Individual sides
<Box pt={2} pr={4} pb={2} pl={4}>Different per side</Box>

Prop	Description
p	All sides
px	Left and right
py	Top and bottom
pt	Top only
pr	Right only
pb	Bottom only
pl	Left only

Margin Props

Margin adds space outside an element's border.

// All sides
<Box m={4}>16px margin on all sides</Box>

// Horizontal and vertical
<Box mx={6} my={3}>24px horizontal, 12px vertical</Box>

// Individual sides
<Box mt={8} mb={4}>32px top, 16px bottom</Box>

Prop	Description
m	All sides
mx	Left and right
my	Top and bottom
mt	Top only
mr	Right only
mb	Bottom only
ml	Left only

Negative Margins

Negative margins are supported using negative multipliers:

// Negative margin to pull element up
<Box mt={-4}>Pulls up by 16px</Box>

// Or with CSS string values
<Box mt="-10px">Custom negative margin</Box>

Gap (Flexbox/Grid)

Use gap for spacing between flex or grid children:

<Box display="flex" gap={4}>
  <Box>Item 1</Box>
  <Box>Item 2</Box>
  <Box>Item 3</Box>
</Box>

For different row and column gaps, use gapRow and gapColumn:

// Grid with different row and column gaps
<Box display="grid" gridTemplateColumns="1fr 1fr" gapRow={4} gapColumn={8}>
  <Box>Cell 1</Box>
  <Box>Cell 2</Box>
  <Box>Cell 3</Box>
  <Box>Cell 4</Box>
</Box>

Prop	Description
gap	Sets both row and column gap
gapRow	Gap between rows (overrides gap for rows)
gapColumn	Gap between columns (overrides gap for columns)

Responsive Spacing

All spacing props support responsive values. Specify different values for each breakpoint:

// Padding that increases with screen size
<Box p={{ base: 2, md: 4, lg: 6 }}>
  8px on mobile, 16px on tablet, 24px on desktop
</Box>

// Responsive gap
<Box display="flex" gap={{ base: 2, md: 4 }}>
  <Box>Item 1</Box>
  <Box>Item 2</Box>
</Box>

// Responsive margins
<Box my={{ base: 4, lg: 8 }}>
  16px vertical margin on mobile, 32px on large screens
</Box>

Breakpoints use a mobile-first cascade—you only need to specify breakpoints where the value changes. See the Responsive guide for more details.

Specificity Cascade

When multiple spacing props apply to the same side, more specific props override less specific ones:

// Result: left=32px, right=24px, top=16px, bottom=16px
<Box p={4} px={6} pl={8} />

// Result: top=32px, bottom=16px
<Box py={4} pt={8} />

// Result: left=24px, right=24px, top=8px, bottom=16px
<Box p={4} px={6} py={2} pb={4} />

Order of specificity (most to least):

1. Individual side (pt, pr, pb, pl)
2. Axis (px, py)
3. All sides (p)

The same applies to margin props (m, mx, my, mt, etc.).

Common Patterns

Card Padding

<Box p={6} bg="surface" rounded="md">
  Card content with comfortable padding
</Box>

Section Spacing

<Box py={12}>
  <Heading mb={6}>Section Title</Heading>
  <Text>Section content with vertical rhythm</Text>
</Box>

Tight Lists

VStack is a convenience component that renders a vertical flex container:

<VStack gap={2}>
  <Text>Item 1</Text>
  <Text>Item 2</Text>
  <Text>Item 3</Text>
</VStack>

Button Groups

HStack is a convenience component that renders a horizontal flex container:

<HStack gap={3}>
  <Button>Cancel</Button>
  <Button>Submit</Button>
</HStack>

Custom Values

For values outside the multiplier system, use CSS strings:

<Box p="20px">Custom 20px padding</Box>
<Box m="2rem">Custom 2rem margin</Box>
<Box p="clamp(16px, 4vw, 32px)">Fluid padding</Box>