Flex

A flexible layout component that uses CSS Flexbox to arrange child components horizontally (row) or vertically (column). It offers control over alignment, justification, gaps, and wrapping, and includes a default top margin of 20 px for vertical spacing.

Use Cases

• Form layouts with side‑by‑side fields (row direction)
• Button groups with horizontal alignment
• Vertical stacking with controlled spacing (column direction)
• Center‑aligned content (both horizontal and vertical centering)
• Responsive layouts with wrap: ‘wrap’ (items wrap to next line on narrow screens)
• Split layouts: image on one side, details on the other (50/50 with equalItems: true)

Properties

direction

Main axis direction - controls whether items flow horizontally (row) or vertically (column). Type: string. Options: row, column. Default: row. Visual impact: row – items arranged horizontally left‑to‑right; column – items arranged vertically top‑to‑bottom. Tip: Use ‘row’ for side‑by‑side form fields or button groups, and ‘column’ for vertical content stacks.

justifyContent

Alignment along main axis (horizontal for row, vertical for column). Type: string. Options: start, center, end. Default: start. Visual impact: start – items aligned to start (left for row, top for column); center – items centered on main axis; end – items aligned to end (right for row, bottom for column). Tip: Use ‘start’ or ‘end’ for left/right button groups; use ‘center’ for centered content.

gap

Spacing between flex items in pixels. Type: number. Default: 24. Visual impact: 0 – no gap; 8 – very tight; 12 – tight; 16 – compact; 24 – balanced (recommended); 32 – generous. Tip: Use 16‑24 px for form fields, 12‑16 px for button groups, 24‑32 px for spaced sections.

wrap

Whether items should wrap to the next line when the container is too narrow. Type: string. Options: wrap, nowrap. Default: wrap. Visual impact: wrap – items wrap on narrow screens (responsive); nowrap – items stay on one line and may shrink or overflow. Tip: Use ‘wrap’ for mobile‑friendly layouts; use ‘nowrap’ when items must stay on a single line.

equalItems

When true, all direct children receive equal width (e.g., a 50/50 split for two items). Type: boolean. Default: false. Visual impact: true – equal width for all items; false – items size based on their content (natural flex behavior).

items

Array of child components to arrange in the flex layout. Type: slot. Required. Minimum items: 1. Example values: Form fields (Input, Dropdown, Date), Buttons, Mixed content (Headings, Text, Images).

customCss

Custom CSS styles for advanced styling of the flex container. Parsed as CSS property‑value pairs. Type: string. Visual impact: Allows background colors, gradients, padding, border‑radius, etc. Tip: Add backgrounds or gradients to group sections, add padding for separation, use border‑radius for a card‑like appearance. Security note: Parsed by cssParser utility; tenants only affect their own pages.

Best Practices

• CRITICAL: ALWAYS set gap: 24 (or 16‑32 px) – without gap, items touch each other with no spacing.
• Default margin‑top: 20 px provides vertical spacing – can be overridden with customCss if needed.
• Use Flex with direction: ‘row’ for horizontal form field pairs.
• Use Flex with direction: ‘column’ for vertical stacking with gaps.
• Set wrap: ‘wrap’ for responsive layouts that adapt to narrow screens.
• Use justifyContent for precise alignment control.
• Prefer Grid when you need equal‑width columns; use Flex for unequal widths or specific alignment needs.

Common Mistakes

Using Flex WITHOUT setting gap property

Why it's a problem: Items touch each other with no spacing – looks cramped and unprofessional.

Fix: ALWAYS set gap: 24 for balanced spacing: {direction: 'row', gap: 24}

Not setting wrap: ‘wrap’ for responsive layouts

Why it's a problem: Items don’t wrap on narrow screens – they shrink or overflow, breaking mobile layout.

Fix: Set wrap: ‘wrap’ when items should stack on mobile (e.g., form fields, button groups).

Using Flex when Grid would be simpler

Why it's a problem: Grid is better for equal‑width columns. Flex requires more configuration for the same result.

Fix: Use Grid for equal‑width multi‑column layouts (2‑column forms). Use Flex for unequal widths or specific alignment needs.

Forgetting to set gap between items

Why it's a problem: Items touch each other with no spacing – looks cramped and unprofessional.

Fix: Always set gap: 24 for balanced spacing between items.

Using direction: ‘row’ without wrap: ‘wrap’ for many items

Why it's a problem: Many items in a row overflow on narrow screens – horizontal scrolling on mobile.

Fix: Set wrap: ‘wrap’ for rows with multiple items that should wrap on mobile.