---
title: "Box"
description: "Free layout: direction, alignment, padding, surface."
---

> Documentation Index
> Fetch the complete documentation index at: https://gistui.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Box

```gistui
root = Box(Icon(name:rocket, tone:accent), Stack("**Launch day**", "Everything is ready.", gap:none), Spacer(), Button("Open", v:secondary), dir:row, gap:md, pad:md, surface:tint, align:center)
```

## Signature

This is the line a model reads in the system prompt.

```gistui
Box(...children, dir:Dir, gap:Gap, align:Align, justify:Justify, pad:none|sm|md|lg|xl, surface:none|card|sunk|tint|outline|inverse|accent|gradient, w:num, text:start|center|end, accent:Accent, wrap, fill, grow)
```

- **Group:** Layout
- **Children:** Yes: any component or text
- **Positional arguments:** none

## Props

| Prop | Type | How to write it | Notes |
|---|---|---|---|
| `dir` | `col` · `row` | named: `dir:…` | Default `"col"`. Also accepts `column`, `vertical`, `horizontal`. |
| `gap` | `none` · `xs` · `sm` · `md` · `lg` · `xl` | named: `gap:…` | Also accepts `small`, `medium`, `large`. |
| `align` | `start` · `center` · `end` · `stretch` · `between` | named: `align:…` |  |
| `justify` | `start` · `center` · `end` · `between` · `around` | named: `justify:…` |  |
| `pad` | `none` · `sm` · `md` · `lg` · `xl` | named: `pad:…` |  |
| `surface` | `none` · `card` · `sunk` · `tint` · `outline` · `inverse` · `accent` · `gradient` | named: `surface:…` |  |
| `wrap` | flag | bare word: `wrap` |  |
| `fill` | flag | bare word: `fill` | children share the space equally |
| `grow` | flag | bare word: `grow` |  |
| `w` | number | named: `w:…` | fixed width in px |
| `text` | `start` · `center` · `end` | named: `text:…` |  |
| `accent` | `neutral` · `slate` · `stone` · `rose` · `pink` · `violet` · `indigo` · `blue` · `teal` · `green` · `orange` · `amber` · `red` | named: `accent:…` | Also accepts `purple`, `gray`, `grey`, `zinc`, `yellow`. |

## Use your own component

Keep the name and schema, swap what is drawn. The prompt and the model's output do not change.

### React

```tsx
import { ui } from "@gistui/react/ui";

const lib = ui.extend({ Box: MyBox });
<GistUI library={lib} stream={response.body} />;
```
### Vue

```vue
<GistUI :source="answer" :components="{ Box: MyBox }" />
```
### Svelte

```svelte
<GistUI source={answer} components={{ Box: MyBox }} />
```
### Solid

```tsx
<GistUI source={answer()} components={{ Box: MyBox }} />
```
### Vanilla

```ts
import { ui } from "@gistui/vanilla/ui";

const lib = ui.extend({ Box: (ctx) => ({ el: myElement(ctx) }) });
```

See [Custom components](/docs/guides/custom-components/) for the full contract. Style hook: `[data-gistui="Box"]`.

Source: https://gistui.com/docs/components/layout/box/index.mdx