Design Mode and the Builder

Design mode is where you build pages visually. Pick Design in the mode switch at the top right of the header. You see three things side by side:

• Builder on the left: the layers of the page you're editing.
• Preview in the middle: your site, running. Click anything to select it.
• Style on the right: the styles of the selected element.

The activity bar on the far left opens the other panels: Add (⌥1), Builder (⌥2), Data (⌥3), AI Chat (⌥4), Style (⌥5), Terminal (⌥6) and Snippets (⌥7).

Everything you do in the Builder is written to your page's Astro code, as if you had typed it yourself. Edits save on their own and show in the preview a moment later. Nothing goes live until you publish.

Pick a page

The page name at the top of the Builder is the page switcher. Click it to:

• Search and open any page, layout or component.
• See how each page renders, with a Static, Dynamic or Cached badge. See Page Rendering.
• Create a New page or a New component.
• Open Page settings (the gear next to a page) for its SEO title, description and social image, its rendering mode, and Duplicate.

The preview follows the page you open, and the Builder follows the page you browse to in the preview.

Select elements

Click an element in the preview, or its row in the Builder. The two stay in sync: selecting a row selects the element on the page, and the other way round.

When something is selected, the preview shows a selection toolbar:

• The element's name. Click it to select one of its parents.
• Edit text, for text. Replace image, for images. Open link, for links.
• AI: describe a change for this element, and the AI Assistant makes it.
• Duplicate and Delete.
• ⋯: open the component the element belongs to, Make editable, Make a component…, View code (C) and Edit classes (E).

The component that holds the selection gets a dashed outline with its name. Clicking something inside a component in the preview opens that component in the Builder and selects it there.

Follow links

A plain click on a link selects it. To go to the page it links to, ⌘-click (Ctrl-click) the link, or use Open link in the selection toolbar. The preview goes there and the Builder opens that page. This needs infrastructure 1.53 or later.

Select several elements

⌘-click (Ctrl-click) or Shift-click rows in the Builder to select several. A bar above the tree offers Group (wrap them in one container), Duplicate, Paste styles and Delete. Each is one change, undone at once.

Edit content

Text on the page

Double-click text in the preview to edit it in place. Shift+Enter adds a line break. This works for text with formatting or icons inside (only the words change), for a component's props (the change is written where the component is used), and for collection entries.

Text that comes from WordPress or WooCommerce can't be changed here: the editor points you to wp-admin instead.

The element's card

Click a row in the Builder and a card opens under it with the element's content:

• Text: type the text, or type / to insert data (see Use data).
• Links: Link URL and Open in a new tab.
• Images: Choose from media, Image URL and Alt text.
• Edit styles opens the Style panel.
• Edit in code opens the element's own markup in a small editor, when the Builder can't edit something directly.

Click the row again, click the × on the card, or press Esc to close it.

Edit styles

The Style panel edits the selected element. Its sections are Layout, Spacing, Typography, Background, Border and Effects, with Classes and Tokens under Advanced. In Tailwind projects, Global classes at the top edits named classes like card or btn-primary that you reuse across the site.

To style the whole site at once (colors, fonts, spacing), use Site ▾ › Site Style. See Site Style.

Breakpoints: Desktop, Tablet, Mobile

The top of the Style panel picks the screen size you're styling. Picking one also shows the preview at that size.

Each size keeps its own values, and switching sizes shows that size's values. Style sections that change by screen size are marked.

Next to the sizes, State styles the element while it is hovered, focused or pressed.

Copy and paste styles

⌥⌘C copies the selected element's styles, and ⌥⌘V pastes them onto another element or onto several selected elements. Both are also in the Builder's right-click menu and in ⌘K.

Add elements

Click Add in the Builder's header (or ⌥1) to open the Add panel next to the tree. It has:

• List from data: cards for the items of a data source, each bound to its item. See Data Sources.
• Elements: Section, Container, Row, Stack, Grid, Heading, Paragraph, Button, Link, List, Divider and Image.
• Components: the components in src/components/, and New component….

Drag an item onto the tree or the preview to put it exactly where you want. Or click it: the line under the search box says where a click adds it ("Click adds inside Pricing › Grid"). Image opens the media library, so you can upload or pick the image to insert.

You can also add from a row: hover it and click +, or right-click it and choose Add Before…, Add After… or Add Inside…. That picker also has Paste HTML… to insert markup you copied from elsewhere.

Components and props

A component is a piece of a page you reuse, like a card or a hero. Components show in the Builder with their own color.

• Edit a use of a component. Click its row: the card shows its props as fields that fit their type (switches for yes/no props, choice lists, number fields, and page and image pickers for links and images).
• Edit the component itself. Double-click its row, or click Edit component in its card. The Builder opens the component's file. While it's open, a chip says where it is used ("On 5 pages: changes apply to all").
• Make a component. Select an element and choose Make a component… (right-click, the selection toolbar's ⋯, or ⌘K). PhantomStudio finds its look-alikes next to it, such as the other cards in the same grid, turns them all into one component, and makes the parts that differ into props. Name the component and its props, then click Create component (or Create and use 3× when it found look-alikes).
• Make editable. Inside a component, Make editable turns fixed text, a link or an image into a prop, so each use can set its own value.

Interactive components

A React, Preact, Solid, Vue or Svelte component on a page has an Interactive choice on its card: No (plain HTML), When visible, Right away, When the page is idle or On small screens only. Interactive components have a ⚡ in the tree. If a component has buttons or state but isn't interactive, the tree marks it and its card offers Make it interactive.

Repeat: show a list of items

Repeat for each… shows an element once for each item in a list, such as one card per post or per team member.

1. Right-click the element in the Builder and choose Repeat for each….
2. Pick the list, name each item (Call each one), and optionally set Show at most.
3. Click Repeat it.

The row then reads as a sentence, such as "Repeat each post in posts · first 6", and shows how many copies the preview renders (×6). Inside the repeated element, use the item's fields with From data, or type / in a text field.

Turn look-alikes into a list

If a page has three hard-coded cards, select one of them (or anything inside one). A suggestion under the tree says how many look alike and offers:

• Make a list: what differs between the cards (titles, texts, links, images) becomes a list of items, and one card repeats for each item.
• Component: one component, with what differs as props.

Turn look-alikes into a list… is also in the right-click menu and ⌘K.

Make a list of your own

In the Data group at the top of the tree, click + List. Name the list, add fields (Text, Long text, Image, Link, Number, Yes / no), fill in the items, and choose where to keep it:

• Only on this page: written into the page's code. Edit it again with Edit items.
• Editable content: a content collection in src/content/ that your clients can edit.

Then use the list with Repeat for each….

Show if: show content conditionally

Show if… shows an element only when a condition is true, such as "the post has an image".

1. Right-click the element and choose Show if….
2. Pick the data, then a Rule: is set, is empty, has items, has no items, is, is not, is more than, is less than or contains. Some rules need a Value.
3. Click Add condition.

The dialog previews the sentence the tree will show, such as "Show if image is set". If the data you need isn't in the list, choose Write it as code. Conditions with an alternative show as "If … / Otherwise".

Use data in text and props

Text fields and component props can show data: a field of the current item in a Repeat, the page's data, or a component's props. Type / in the field, or use its data button (From data). Data shows as a chip such as feature › description. When the value is written in the file, the field shows what it will display.

The Data group at the top of the tree lists what the page works with: collections, CMS data, data files, lists written in the page and fetches. In a component it also lists the props and where each is used. Hover an item to outline everything on the page that uses it.

To see everything on the page that shows data, turn on X-ray in the preview toolbar. It colors each element by where its data comes from (WordPress, a collection, props…) and labels Repeats and Show ifs.

Template pages and the preview pager

A template page makes one page for each entry of a list, such as src/pages/events/[slug].astro for every event. When you open one, the preview shows one entry, and the preview toolbar gets a pager: previous, next, or pick an entry by its title. This works for collection entries and for WordPress posts, pages and custom post types. See Data Sources.

Undo and redo

The Builder's header has Undo (⌘Z) and Redo (⌘⇧Z). Each message says what was undone ("Undid: Repeat each recipe in recipes: Card") and offers the opposite. After an edit, the changed element pulses in the preview and its row flashes in the tree.

The Builder won't save an edit that would break the page: it undoes the edit and says what would have gone wrong.

Keyboard shortcuts

With the Builder focused:

Press ? anywhere outside a text field for the full list.

Next steps

• The Builder Tree: rows, the right-click menu and drag and drop in detail
• Data Sources: connect WordPress or Sanity, and create collections
• Page Rendering: choose when each page is built
• Publishing: put your changes on the live site