Spacer

The Spacer component has been removed in HeroUI v3. Use Tailwind CSS margin utilities directly instead.

Overview

The Spacer component was a simple utility component used to add spacing between elements using margin. In v3, you should use Tailwind CSS margin utility classes directly, which is more flexible and follows standard Tailwind patterns.

Key Changes

1. Component Removal

v2: <Spacer> component from @heroui/react
v3: Tailwind CSS margin utilities (ml-*, mr-*, mt-*, mb-*, mx-*, my-*)

2. Props Mapping

The v2 Spacer component had the following props that map to Tailwind utilities:

v2 Prop	v3 Equivalent	Notes
`x={n}`	`ml-{n}` or `mx-{n}`	Horizontal margin (left or both sides)
`y={n}`	`mt-{n}` or `my-{n}`	Vertical margin (top or both sides)
`isInline`	`inline-block` or `block`	Display type

3. Spacing Scale

The spacing values in v2 match Tailwind's spacing scale:

x={1} → ml-1 (0.25rem / 4px)
x={2} → ml-2 (0.5rem / 8px)
x={4} → ml-4 (1rem / 16px)
y={4} → mt-4 (1rem / 16px)
etc.

Migration Examples

Basic Vertical Spacing

import { Spacer } from "@heroui/react";

export default function App() {
  return (
    <div>
      <div>Item 1</div>
      <Spacer y={4} />
      <div>Item 2</div>
      <Spacer y={4} />
      <div>Item 3</div>
    </div>
  );
}

export default function App() {
  return (
    <div>
      <div>Item 1</div>
      <div className="mt-4">Item 2</div>
      <div className="mt-4">Item 3</div>
    </div>
  );
}

Basic Horizontal Spacing

import { Spacer } from "@heroui/react";

export default function App() {
  return (
    <div className="flex">
      <div>Item 1</div>
      <Spacer x={4} isInline />
      <div>Item 2</div>
      <Spacer x={4} isInline />
      <div>Item 3</div>
    </div>
  );
}

export default function App() {
  return (
    <div className="flex">
      <div>Item 1</div>
      <div className="ml-4">Item 2</div>
      <div className="ml-4">Item 3</div>
    </div>
  );
}

Using Gap (Recommended for Flex/Grid)

For flex and grid layouts, using gap is often better than Spacer:

import { Spacer } from "@heroui/react";

export default function App() {
  return (
    <div className="flex">
      <div>Item 1</div>
      <Spacer x={4} isInline />
      <div>Item 2</div>
      <Spacer x={4} isInline />
      <div>Item 3</div>
    </div>
  );
}

export default function App() {
  return (
    <div className="flex gap-4">
      <div>Item 1</div>
      <div>Item 2</div>
      <div>Item 3</div>
    </div>
  );
}

Vertical Layout with Spacing

import { Spacer } from "@heroui/react";

export default function App() {
  return (
    <div className="flex flex-col">
      <Button>Button 1</Button>
      <Spacer y={2} />
      <Button>Button 2</Button>
      <Spacer y={2} />
      <Button>Button 3</Button>
    </div>
  );
}

import { Button } from "@heroui/react";

export default function App() {
  return (
    <div className="flex flex-col gap-2">
      <Button>Button 1</Button>
      <Button>Button 2</Button>
      <Button>Button 3</Button>
    </div>
  );
}

Different Spacing Values

import { Spacer } from "@heroui/react";

<Spacer x={1} />   {/* 0.25rem */}
<Spacer x={2} />   {/* 0.5rem */}
<Spacer x={4} />   {/* 1rem */}
<Spacer x={8} />   {/* 2rem */}
<Spacer y={1} />   {/* 0.25rem */}
<Spacer y={2} />   {/* 0.5rem */}
<Spacer y={4} />   {/* 1rem */}
<Spacer y={8} />   {/* 2rem */}

<div className="ml-1" />   {/* 0.25rem */}
<div className="ml-2" />   {/* 0.5rem */}
<div className="ml-4" />   {/* 1rem */}
<div className="ml-8" />   {/* 2rem */}
<div className="mt-1" />   {/* 0.25rem */}
<div className="mt-2" />   {/* 0.5rem */}
<div className="mt-4" />   {/* 1rem */}
<div className="mt-8" />   {/* 2rem */}

Combined X and Y Spacing

import { Spacer } from "@heroui/react";

<Spacer x={4} y={2} />

<div className="ml-4 mt-2" />

Complete Example

import { Spacer, Button } from "@heroui/react";

export default function App() {
  return (
    <div>
      <h1>Title</h1>
      <Spacer y={4} />
      <p>Description text</p>
      <Spacer y={8} />
      <div className="flex">
        <Button>Cancel</Button>
        <Spacer x={4} isInline />
        <Button>Submit</Button>
      </div>
    </div>
  );
}

import { Button } from "@heroui/react";

export default function App() {
  return (
    <div>
      <h1>Title</h1>
      <p className="mt-4">Description text</p>
      <div className="mt-8 flex gap-4">
        <Button>Cancel</Button>
        <Button>Submit</Button>
      </div>
    </div>
  );
}

Spacing Scale Reference

Tailwind CSS spacing scale (matches v2 Spacer values):

Value	Size	Tailwind Class
`0`	0px	`m-0`, `ml-0`, `mt-0`, etc.
`px`	1px	`m-px`, `ml-px`, `mt-px`, etc.
`0.5`	0.125rem (2px)	`m-0.5`, `ml-0.5`, `mt-0.5`, etc.
`1`	0.25rem (4px)	`m-1`, `ml-1`, `mt-1`, etc.
`2`	0.5rem (8px)	`m-2`, `ml-2`, `mt-2`, etc.
`3`	0.75rem (12px)	`m-3`, `ml-3`, `mt-3`, etc.
`4`	1rem (16px)	`m-4`, `ml-4`, `mt-4`, etc.
`5`	1.25rem (20px)	`m-5`, `ml-5`, `mt-5`, etc.
`6`	1.5rem (24px)	`m-6`, `ml-6`, `mt-6`, etc.
`8`	2rem (32px)	`m-8`, `ml-8`, `mt-8`, etc.
`10`	2.5rem (40px)	`m-10`, `ml-10`, `mt-10`, etc.
`12`	3rem (48px)	`m-12`, `ml-12`, `mt-12`, etc.
`16`	4rem (64px)	`m-16`, `ml-16`, `mt-16`, etc.
`20`	5rem (80px)	`m-20`, `ml-20`, `mt-20`, etc.

Best Practices

1. Use Gap for Flex/Grid Layouts

Instead of Spacer components, use gap utilities:

// ✅ Recommended
<div className="flex gap-4">
  <Button>Button 1</Button>
  <Button>Button 2</Button>
</div>

// ❌ Not recommended
<div className="flex">
  <Button>Button 1</Button>
  <div className="ml-4"><Button>Button 2</Button></div>
</div>

2. Use Space Utilities for Vertical Lists

// ✅ Recommended
<div className="space-y-4">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>

// Alternative
<div>
  <div>Item 1</div>
  <div className="mt-4">Item 2</div>
  <div className="mt-4">Item 3</div>
</div>

3. Use Margin Utilities Directly

Apply margin directly to elements instead of using Spacer:

// ✅ Recommended
<div className="mt-4">Content</div>

// ❌ Not recommended
<>
  <Spacer y={4} />
  <div>Content</div>
</>

Creating a Reusable Spacer Component (Optional)

If you frequently need spacer-like behavior, you can create a simple wrapper:

import { Spacer } from "@heroui/react";

<Spacer x={4} y={2} />

interface SpacerProps {
  x?: number | string;
  y?: number | string;
  className?: string;
}

export function Spacer({ x, y, className }: SpacerProps) {
  const classes = [];
  if (x) classes.push(`ml-${x}`);
  if (y) classes.push(`mt-${y}`);
  
  return <div className={[classes.join(" "), className].filter(Boolean).join(" ")} aria-hidden="true" />;
}

// Usage
<Spacer x={4} y={2} />

However, it's recommended to use Tailwind utilities directly instead of creating a wrapper component.

Breaking Changes Summary

Component Removed: Spacer component no longer exists in v3
Import Change: Remove import { Spacer } from "@heroui/react"
Use Tailwind Utilities: Replace with margin utilities (ml-*, mt-*, mx-*, my-*)
Use Gap: Prefer gap-* utilities for flex/grid layouts
Use Space: Prefer space-y-* and space-x-* for consistent spacing

Migration Steps

Remove Import: Remove Spacer from @heroui/react imports
Replace Spacer: Replace <Spacer x={n} /> with ml-{n} or mx-{n} classes
Replace Spacer: Replace <Spacer y={n} /> with mt-{n} or my-{n} classes
Use Gap: For flex/grid layouts, use gap-{n} instead of Spacer
Use Space: For vertical/horizontal lists, use space-y-{n} or space-x-{n}

Tips for Migration

Prefer Gap: Use gap-* utilities for flex and grid layouts - it's cleaner and more semantic
Use Space Utilities: Use space-y-* and space-x-* for consistent spacing between children
Apply Directly: Apply margin classes directly to elements instead of using spacer components
Responsive Spacing: Use responsive variants like mt-4 md:mt-8 for different screen sizes
Negative Margins: Tailwind supports negative margins (-ml-4) if needed
Arbitrary Values: Use arbitrary values like ml-[13px] for custom spacing

Common Patterns

Vertical Stack with Spacing

// Using space-y utility
<div className="space-y-4">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>

Horizontal Row with Spacing

// Using gap utility
<div className="flex gap-4">
  <Button>Button 1</Button>
  <Button>Button 2</Button>
  <Button>Button 3</Button>
</div>

Custom Spacing Between Specific Elements

<div>
  <div>Item 1</div>
  <div className="mt-8">Item 2 (with custom spacing)</div>
  <div className="mt-4">Item 3</div>
</div>

Need Help?

For spacing guidance:

For community support:

On this page