@fiscozen/container

A flexible layout component for organizing content with controlled spacing. Supports both vertical and horizontal orientations with customizable gap sizes.

Features

• Vertical and horizontal layout orientations
• Layout variants for horizontal containers (expand-first, with more coming)
• Customizable gap sizes (sm, base, lg)
• Main and section container variants with different spacing scales
• Flexible HTML tag rendering

Installation

npm install @fiscozen/container

Basic Usage

Vertical Layout (Default)

<script setup>
import { FzContainer } from '@fiscozen/container'
</script>

<template>
  <FzContainer main>
    <FzContainer>
      <div>Item 1</div>
      <div>Item 2</div>
      <div>Item 3</div>
    </FzContainer>

    <FzContainer>
      <div>Item 1</div>
      <div>Item 2</div>
      <div>Item 3</div>
    </FzContainer>
  </FzContainer>
</template>

Horizontal Layout

<template>
  <FzContainer horizontal>
    <button>Action 1</button>
    <button>Action 2</button>
    <button>Action 3</button>
  </FzContainer>
</template>

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | main | boolean | false | If true, uses main container spacing (larger gaps for page-level sections) | | gap | 'sm' \| 'base' \| 'lg' (when main={true})'none' \| 'xs' \| 'sm' \| 'base' \| 'lg' (when main={false}) | 'base' | Gap size between elements. Available values depend on container type | | horizontal | boolean | false | If true, elements align horizontally. Otherwise, vertically (default) | | layout | 'default' \| 'expand-first' \| 'expand-all' \| 'space-between' | 'default' | Layout behavior for horizontal containers (controls how child elements expand). Only applies when horizontal is true | | alignItems | 'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline' | 'stretch' for vertical, 'center' for horizontal | Alignment of child elements on the cross-axis. In vertical containers: horizontal alignment (left/center/right). In horizontal containers: vertical alignment (top/center/bottom) | | tag | string | 'div' | HTML tag to use for the container element |

Gap Sizes

The component uses CSS custom properties for consistent spacing across the design system.

Main Containers (main={true})

| Size | CSS Variable | Value | |------|--------------|-------| | sm | --main-content-sm | 32px | | base | --main-content-base | 48px | | lg | --main-content-lg | 64px |

Section Containers (main={false} or default)

| Size | CSS Variable | Value | |------|--------------|-------| | none | --section-content-none | 0px | | xs | --section-content-xs | 8px | | sm | --section-content-sm | 16px | | base | --section-content-base | 24px | | lg | --section-content-lg | 32px |

Main containers are intended for page-level sections and use larger spacing values. Section containers are for content within sections and use smaller spacing values, with additional none and xs options for tighter layouts.

Orientation Behavior

Vertical (default)

• Elements stack vertically
• Gap is applied between elements vertically
• Special spacing for consecutive paragraphs (p + p) for improved readability
• Default layout for most use cases
• Default alignment: alignItems="stretch" (elements expand to full width)

Horizontal

• Elements align horizontally in a single row
• Gap is applied between elements horizontally
• No wrapping (flex-wrap: nowrap) - elements will shrink to fit
• Ideal for action buttons, inline controls, or horizontal navigation
• Supports layout variants via the layout prop (see Layout Behavior section below)
• Default alignment: alignItems="center" (vertically centered)

Layout Behavior (Horizontal Only)

The layout prop controls how child elements expand to fill available space in horizontal containers. This prop only works when horizontal is true.

Available Layouts

| Layout | Status | Description | |--------|--------|-------------| | default | Implemented | All elements maintain their natural size (flex-grow: 0). This is the default behavior. | | expand-first | Implemented | The first element expands to fill available space (flex-grow: 1), while other elements maintain their natural size. | | expand-all | Implemented | All elements expand equally to fill available space (flex-grow: 1 on all children). | | space-between | Implemented | Elements are distributed with space between them (justify-content: space-between). Elements maintain their natural size. | | expand-last | Future | The last element will expand to fill available space, while other elements maintain their natural size. |

When to Use Each Layout

default: Use when all elements should maintain their natural size. Good for button groups, navigation items, or any horizontal list where elements should not grow.

expand-first: Use when you want the first element to take up all remaining space.

expand-all: Use when you want all elements to have equal width.

space-between: Use when you want elements to maintain their natural size but be distributed across the available space.

AlignItems Behavior

The alignItems prop controls how child elements are aligned on the cross-axis (perpendicular to the main axis).

For Vertical Containers

Controls horizontal alignment of elements:

stretch (default): Elements stretch to fill container width start: Elements align to the left center: Elements are centered horizontally end: Elements align to the right baseline: Elements align along their text baseline

For Horizontal Containers

Controls vertical alignment of elements:

start: Elements align to the top center (default): Elements are centered vertically end: Elements align to the bottom stretch: Elements stretch to fill container height baseline: Elements align along their text baseline (useful for text)

Examples

Nested Containers with Different Gaps

<template>
  <FzContainer main gap="lg">
    <h1>Page Title</h1>
    
    <FzContainer>
      <h2>Section Title</h2>
      <p>Content paragraph 1</p>
      <p>Content paragraph 2</p>
    </FzContainer>
    
    <FzContainer gap="sm">
      <label>Form Label</label>
      <input type="text" />
      <span>Helper text</span>
    </FzContainer>
  </FzContainer>
</template>

Horizontal Button Group

<template>
  <FzContainer horizontal gap="sm">
    <button>Cancel</button>
    <button>Save Draft</button>
    <button>Publish</button>
  </FzContainer>
</template>

Custom HTML Tag

<template>
  <FzContainer tag="section" main>
    <h1>Section Content</h1>
    <p>This container renders as a section element</p>
  </FzContainer>
</template>

Layout: Expand First (Task List)

<template>
  <FzContainer gap="sm">
    <FzContainer horizontal layout="expand-first" gap="base">
      <FzContainer gap="sm">
        <p>Task name that can be very long</p>
        <p>Task description that will expand to fill available space</p>
      </FzContainer>
      <button>Complete</button>
    </FzContainer>
    
    <FzContainer horizontal layout="expand-first" gap="base">
      <FzContainer gap="sm">
        <p>Another task</p>
        <p>With another description</p>
      </FzContainer>
      <button>Complete</button>
    </FzContainer>
  </FzContainer>
</template>

Layout: Expand First (Form Actions)

<template>
  <FzContainer gap="base">
    <input type="text" placeholder="Form field..." />
    <input type="text" placeholder="Another field..." />
    
    <!-- Actions aligned to the right -->
    <FzContainer horizontal layout="expand-first" gap="base">
      <FzContainer></FzContainer>
      <FzContainer horizontal gap="sm">
        <button>Cancel</button>
        <button>Save</button>
      </FzContainer>
    </FzContainer>
  </FzContainer>
</template>

Layout: Expand All

<template>
  <FzContainer horizontal layout="expand-all" gap="base">
    <button>Button 1</button>
    <button>Button 2</button>
    <button>Button 3</button>
  </FzContainer>
</template>

Layout: Expand All

<template>
  <FzContainer horizontal layout="expand-all" gap="lg">
    <div class="card">
      <h3>Card 1</h3>
      <p>Content here</p>
    </div>
    <div class="card">
      <h3>Card 2</h3>
      <p>Content here</p>
    </div>
    <div class="card">
      <h3>Card 3</h3>
      <p>Content here</p>
    </div>
  </FzContainer>
</template>

Layout: Space Between

<template>
  <FzContainer horizontal layout="space-between" gap="base">
    <div class="logo">Logo</div>
    <nav>
      <FzContainer horizontal gap="sm">
        <a href="#">Home</a>
        <a href="#">About</a>
        <a href="#">Contact</a>
      </FzContainer>
    </nav>
  </FzContainer>
</template>

Layout: Space Between

<template>
  <FzContainer horizontal layout="space-between" gap="base">
    <FzContainer gap="xs">
      <h1>Page Title</h1>
      <p>Subtitle or description</p>
    </FzContainer>
    <FzContainer horizontal gap="sm">
      <button>Cancel</button>
      <button>Save</button>
    </FzContainer>
  </FzContainer>
</template>

AlignItems: Vertical Container with Center Alignment

<template>
  <FzContainer alignItems="center" gap="base">
    <h1>Centered Title</h1>
    <p>Centered paragraph</p>
    <button>Centered button</button>
  </FzContainer>
</template>

AlignItems: Vertical Container with Right Alignment

<template>
  <FzContainer alignItems="end" gap="sm">
    <p>Amount: €100</p>
    <p>Tax: €22</p>
    <p>Total: €122</p>
  </FzContainer>
</template>

AlignItems: Horizontal Container with Top Alignment

<template>
  <FzContainer horizontal alignItems="start" gap="base">
    <img src="icon.png" style="height: 40px" />
    <div>
      <h3>Title</h3>
      <p>Description</p>
    </div>
  </FzContainer>
</template>

AlignItems: Horizontal Container with Baseline Alignment

<template>
  <FzContainer horizontal alignItems="baseline" gap="base">
    <span style="font-size: 0.75rem">Small text</span>
    <span style="font-size: 1rem">Medium text</span>
    <span style="font-size: 1.5rem">Large text</span>
  </FzContainer>
</template>

Typography Notes

When using vertical orientation, the component applies special spacing between consecutive paragraph elements (<p>) to improve readability. This spacing is controlled by the --paragraph-gap CSS custom property and overrides the default gap for better typography.

This special spacing does not apply in horizontal orientation as horizontal paragraph layouts are uncommon.

Accessibility

The component renders semantic HTML and can be customized using the tag prop to use appropriate semantic elements (e.g., form) based on your content structure.