Skip to main content

​
Overview

The Box widget is a versatile container that provides borders, padding, shadows, and layout control. It’s the primary building block for creating structured layouts.

​
Basic Usage

import { ui } from '@rezi-ui/core';

// Simple box with border
ui.box({ border: 'rounded' }, [
  ui.text('Content inside box')
])

// Box with padding and title
ui.box({ border: 'single', title: 'Settings', p: 1 }, [
  ui.text('Configuration options')
])

// Elevated card
ui.box({ preset: 'elevated' }, [
  ui.text('Card content')
])

​
Props

​
border
BorderStyle
default:"'none'"
Border style for the box.
  • "none" - No border
  • "single" - Single-line border
  • "double" - Double-line border
  • "rounded" - Rounded corners
  • "heavy" - Heavy/thick border
  • "dashed" - Dashed border
  • "heavy-dashed" - Heavy dashed border
​
preset
BoxPreset
Style preset applied before explicit props.
  • "card" - Rounded border with padding
  • "surface" - Padding only, no border
  • "well" - Single border with padding
  • "elevated" - Rounded border with shadow and padding
​
title
string
Optional title rendered in the top border.
​
titleAlign
'left' | 'center' | 'right'
default:"'left'"
Alignment of title within the top border.
​
p
SpacingValue
Padding on all sides. Accepts number (cells) or spacing key ("xs", "sm", "md", "lg", "xl", "2xl").
​
px
SpacingValue
Horizontal padding (left and right).
​
py
SpacingValue
Vertical padding (top and bottom).
​
pt
SpacingValue
Top padding.
​
pr
SpacingValue
Right padding.
​
pb
SpacingValue
Bottom padding.
​
pl
SpacingValue
Left padding.
​
gap
SpacingValue
Gap between box children when laid out by the synthetic inner column.
​
shadow
boolean | BoxShadow
Enable shadow effect for depth. Pass true for default shadow, or an object for custom configuration.
​
style
TextStyle
Style applied to the box surface (for borders and background fill). When bg is provided, the renderer fills the box rect.
​
borderStyle
TextStyle
Style applied only to the box border and title. When set, decouples border appearance from child content.
​
inheritStyle
TextStyle
Style inherited by descendants when they do not override their own style. Unlike style, this does not force container background fill.
​
borderTop
boolean
Render top border side.
​
borderRight
boolean
Render right border side.
​
borderBottom
boolean
Render bottom border side.
​
borderLeft
boolean
Render left border side.
​
overflow
'visible' | 'hidden' | 'scroll'
default:"'visible'"
Child overflow behavior.
​
scrollX
number
Horizontal scroll offset in cells (when overflow is "scroll").
​
scrollY
number
Vertical scroll offset in cells (when overflow is "scroll").
​
scrollbarVariant
'minimal' | 'classic' | 'modern' | 'dots' | 'thin'
default:"'minimal'"
Scrollbar glyph variant for overflow: "scroll".
​
scrollbarStyle
TextStyle
Optional style override for rendered scrollbars.
​
opacity
number
default:"1"
Surface opacity in [0..1].
​
theme
ScopedThemeOverride
Optional scoped theme override for this container subtree.
​
transition
TransitionSpec
Optional declarative transition settings for this container.
​
exitTransition
TransitionSpec
Optional declarative exit transition before unmount removal.
​
id
string
Optional unique identifier.
​
key
string
Optional reconciliation key.

​
Layout Constraints

Box also accepts all layout constraint props:
  • width, height - Fixed or percentage dimensions
  • minWidth, minHeight - Minimum constraints
  • maxWidth, maxHeight - Maximum constraints
  • flex, flexShrink, flexBasis - Flex properties
  • alignSelf - Cross-axis alignment override

​
Border Styles

Box supports multiple border styles: 
// Single-line border
ui.box({ border: 'single' }, [ui.text('Content')])

// Rounded corners
ui.box({ border: 'rounded' }, [ui.text('Content')])

// Double-line border
ui.box({ border: 'double' }, [ui.text('Content')])

// Heavy border
ui.box({ border: 'heavy' }, [ui.text('Content')])

// Dashed border
ui.box({ border: 'dashed' }, [ui.text('Content')])

​
Presets

Use presets for common box patterns: 
// Card - rounded border with padding
ui.box({ preset: 'card' }, [ui.text('Card content')])

// Surface - padding only, no border
ui.box({ preset: 'surface' }, [ui.text('Surface content')])

// Well - single border with padding
ui.box({ preset: 'well' }, [ui.text('Well content')])

// Elevated - rounded border with shadow
ui.box({ preset: 'elevated' }, [ui.text('Elevated card')])
Preset props are applied before explicit props, so you can override preset values.

​
Padding

Control spacing inside the box: 
// All sides
ui.box({ p: 2 }, [ui.text('Content')])

// Horizontal and vertical
ui.box({ px: 2, py: 1 }, [ui.text('Content')])

// Individual sides
ui.box({ pt: 1, pr: 2, pb: 1, pl: 2 }, [ui.text('Content')])

// Using spacing scale
ui.box({ p: 'lg' }, [ui.text('Content')])

​
Shadows

Add depth with shadows: 
// Default shadow
ui.box({ border: 'rounded', shadow: true }, [
  ui.text('Card with shadow')
])

// Custom shadow
ui.box({
  border: 'rounded',
  shadow: { offsetX: 2, offsetY: 2, density: 'medium' }
}, [
  ui.text('Custom shadow')
])

​
Titles

Add titles to bordered boxes: 
// Left-aligned title (default)
ui.box({ border: 'single', title: 'Settings' }, [
  ui.text('Configuration')
])

// Centered title
ui.box({ border: 'rounded', title: 'Dialog', titleAlign: 'center' }, [
  ui.text('Message')
])

// Right-aligned title
ui.box({ border: 'single', title: 'Info', titleAlign: 'right' }, [
  ui.text('Details')
])

​
Partial Borders

Render individual border sides: 
// Bottom border only
ui.box({
  border: 'single',
  borderTop: false,
  borderLeft: false,
  borderRight: false,
  borderBottom: true
}, [
  ui.text('Content with bottom border')
])

​
Scrollable Content

ui.box({
  border: 'rounded',
  height: 10,
  overflow: 'scroll',
  scrollY: state.scrollOffset
}, [
  ui.column({ gap: 0 }, longContentList)
])

​
Layout Container

Box automatically creates an inner column for multiple children: 
ui.box({ border: 'rounded', p: 1, gap: 1 }, [
  ui.text('Item 1'),
  ui.text('Item 2'),
  ui.text('Item 3')
])
// Children are laid out vertically with gap: 1

​
Styling Examples

​
Colored Borders

ui.box({
  border: 'rounded',
  borderStyle: { fg: { r: 0, g: 150, b: 255 } },
  p: 1
}, [
  ui.text('Blue border')
])

​
Background Fill

ui.box({
  border: 'rounded',
  style: { bg: { r: 30, g: 33, b: 41 } },
  p: 1
}, [
  ui.text('Dark background')
])

​
Separate Border and Content Styles

ui.box({
  border: 'single',
  borderStyle: { fg: { r: 100, g: 100, b: 100 } },
  style: { bg: { r: 20, g: 20, b: 20 } },
  p: 1
}, [
  ui.text('Gray border, dark background')
])

​
Common Patterns

​
Card Component

ui.box({ preset: 'card', title: 'User Profile' }, [
  ui.text('Name: John Doe'),
  ui.text('Email: [email protected]'),
  ui.text('Role: Developer')
])

​
Panel with Header

ui.box({ border: 'rounded', p: 1, gap: 1 }, [
  ui.text('Settings', { variant: 'heading' }),
  ui.divider(),
  ui.text('Option 1'),
  ui.text('Option 2')
])

ui.box({
  preset: 'elevated',
  width: 60,
  minHeight: 20,
  title: 'Confirm Action',
  titleAlign: 'center'
}, [
  ui.text('Are you sure you want to continue?'),
  ui.row({ gap: 1, justify: 'end' }, [
    ui.button('cancel', 'Cancel'),
    ui.button('confirm', 'Confirm')
  ])
])
  • Row - Horizontal layout container
  • Column - Vertical layout container
  • Card - High-level card component
  • Panel - Titled panel helper

Build docs developers (and LLMs) love

Get started for freeTalk to us