Understanding the Formats
Boxel achieves composability by leveraging various formats that let a card or field be included in another UI. A familiar example is the Card Browser. When you open it in a workspace, you see cards in Tile or Strip view. These tiles and strips are rendered by the Fitted Format of the cards. Each card can have its own fitted format.
For any card you created, you can instruct the AI to create a unique fitted format that presents data in a specific priority, adopts a certain look and feel driven by the existing Isolated View, or redesigns both views together.
To create a custom fitted view:
- Navigate to the Fitted View Preview panel.
- Here you can see the sub‑formats—Badge, Strip, Tiles, and Card.
- Ask for changes (e.g., “I want the strip to show more info,” or “Make the badge use the accent color on a white background”).
The vocabularies shown in preview panels are recognized by Boxel AI, so you can chat naturally to adjust the full format or only a sub‑format. The fitted format is written as a single template in the code editor, with special instructions for each sub‑format based on the width and height available to that card. In Card Browser, Boxel provides the card‑grid tile size that the AI optimizes for. If a size doesn’t look right, specify it by name (e.g., double strip) or dimensions; the AI can update the stylesheet. Fitted views rely on CSS container queries to adapt elements to the available space provided by the parent. Because of CSS limitations, some content may be partially cropped; that’s normal for this platform.
Embedded Format
When you need a card to take as much space as necessary inside another document—say, embedding a to‑do list in a program plan—use the Embedded Format instead of the fitted format. Embedded views fill the full width and expand in height as needed, typically with one optimal size. They may not look as tidy as fitted views. As a rule of thumb, delegate tiled or grid layouts to fitted views and use embedded views when you need to display more information.
Atom Format
The Atom Format displays cards as pills inline with text (e.g., a company pill you can click). Every card or field has a default atom view, but you can override it to show different information in very limited space. You’ve already seen atom formats when the AI assistant shows attached files as pills.
Edit Format
Every card comes with a default Edit Format that lets you edit data according to the schema. You can overwrite it with a domain‑specific edit format (e.g., sliders or compact visualizations). If you need to revert, rename your custom edit format (e.g., to edit2); Boxel will fall back to the default. The AI always creates an edit format for new fields (for compactness) but not for new cards unless you request it. We suggest creating an edit format only after the schema and other formats are stable—adding it too soon increases code‑generation costs if you later change the schema.
Isolated Format
The Isolated Format is the primary view of your card. It has one option: wide format, which lets a card take the full screen width—ideal for dashboards or full‑screen apps. An isolated template can include other cards in two ways:
Data‑only approach – redraws all layout/text while sourcing data from another card.
Delegated rendering – lets another card render a portion of the layout via its embedded, fitted, atom, or edit view.
Boxel AI knows when to use a model‑driven (fully custom) approach versus delegated rendering. Delegated rendering usually provides better navigation, allowing users to click through without extra hints. Use it whenever possible; reserve full custom drawing for high‑design scenarios.
Example: Some isolated templates delegate rendering; others draw everything themselves but only use dependent cards for data.
You can learn more by remixing cards from the catalog and inspecting them in the Preview pane to see how these composable units work in Boxel.
