# Box

> Flexible container for layout and surface styling with full control.

**URL:** https://inference.sh/docs/agents/widgets/box
**Last updated:** 2026-09-18

---

Flexible container for layout and surface styling with full control.

## Preview

```
┌─────────────────────┐
│  Inside a box       │
│  with padding       │
│  and background     │
└─────────────────────┘
```

## Usage

```go
node := models.WidgetNode{
    Type:       models.WidgetNodeTypeBox,
    Padding:    4,
    Background: "surface-secondary",
    Radius:     "md",
    Children: []models.WidgetNode{
        {Type: models.WidgetNodeTypeText, Value: "Content"},
    },
}
```

## Props

| Name | Type | Description | Default |
|------|------|-------------|---------|
| `type` | `"box"` | Node type | required |
| `children` | `WidgetNode[]` | Child components | - |
| `direction` | `"row" \| "col"` | Flex direction | `"col"` |
| `align` | `string` | Cross-axis alignment: `start`, `center`, `end`, `baseline`, `stretch` | - |
| `justify` | `string` | Main-axis distribution: `start`, `center`, `end`, `between`, `around`, `evenly` | - |
| `wrap` | `string` | Wrap behavior: `nowrap`, `wrap`, `wrap-reverse` | - |
| `flex` | `string \| number` | Flex grow/shrink factor | - |
| `gap` | `number \| string` | Gap between children | - |
| `padding` | `number \| string \| object` | Inner padding | - |
| `margin` | `number \| string \| object` | Outer margin | - |
| `border` | `number \| object` | Border styling | - |
| `background` | `string \| ThemeColor` | Background color | - |
| `radius` | `string` | Border radius token | - |
| `height` | `number \| string` | Explicit height | - |
| `width` | `number \| string` | Explicit width | - |
| `minHeight` | `number \| string` | Minimum height | - |
| `maxWidth` | `number \| string` | Maximum width | - |
| `aspectRatio` | `number \| string` | Aspect ratio (e.g., 16/9) | - |

### Background Tokens

**Surface colors:**
- `surface` - Default background
- `surface-secondary` - Slightly offset
- `surface-tertiary` - More offset
- `surface-elevated` - Raised appearance
- `surface-elevated-secondary` - Raised + offset

**Primitive colors:**
- `red-100` through `red-900`
- `blue-100` through `blue-900`
- `gray-100` through `gray-900`
- etc.

### Radius Tokens

`2xs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `4xl`, `full`, `none`

## Examples

### Card-like Container

```go
{
    Type:       models.WidgetNodeTypeBox,
    Padding:    4,
    Background: "surface-secondary",
    Radius:     "lg",
    Border:     1,
    Children: []models.WidgetNode{
        {Type: models.WidgetNodeTypeTitle, Value: "Card Title"},
        {Type: models.WidgetNodeTypeText, Value: "Card content goes here"},
    },
}
```

### Centered Content

```go
{
    Type:    models.WidgetNodeTypeBox,
    Align:   "center",
    Justify: "center",
    Height:  200,
    Children: []models.WidgetNode{
        {Type: models.WidgetNodeTypeText, Value: "Centered!"},
    },
}
```

### With Border

```go
{
    Type:    models.WidgetNodeTypeBox,
    Padding: 3,
    Border: map[string]interface{}{
        "size":  1,
        "color": "subtle",
        "style": "dashed",
    },
    Radius: "md",
    Children: []models.WidgetNode{
        {Type: models.WidgetNodeTypeText, Value: "Dashed border"},
    },
}
```

### Horizontal with Spacing

```go
{
    Type:      models.WidgetNodeTypeBox,
    Direction: "row",
    Gap:       4,
    Align:     "center",
    Justify:   "between",
    Children: []models.WidgetNode{
        {Type: models.WidgetNodeTypeText, Value: "Left"},
        {Type: models.WidgetNodeTypeText, Value: "Right"},
    },
}
```

## Box vs Row vs Col

| Use... | When... |
|--------|---------|
| **Box** | Need full layout control (background, border, sizing) |
| **Row** | Simple horizontal layout |
| **Col** | Simple vertical layout |

## TypeScript

```typescript
const node: WidgetNode = {
  type: "box",
  padding: 4,
  background: "surface-secondary",
  radius: "md",
  children: [
    { type: "text", value: "Content" },
  ],
}
```

## Best Practices

1. **Use for styled containers** - When you need background/border/radius
2. **Use Row/Col for simple layouts** - Less verbose
3. **Be mindful of nesting** - Deep box nesting hurts readability
4. **Use semantic backgrounds** - Surface tokens adapt to themes