# Section Layouts

## Section Layouts

**Skill level:** Beginner · **Time:** 1 minute per section

Most Homio sections can be drawn in more than one way. The hero has four looks, the reviews eight, the services seven. You pick one with a single line, and the section keeps its copy:

```yaml
options:
  layout: "carousel"
```

No code changes: every layout of a section reads the same fields. A few layouts use an extra optional field (a second photo, a list of logos), shown as a comment in the section file.

### Where To Set A Layout
| Set it in… | It applies to… |
| --- | --- |
| The section file, `src/content/sections/<language>/<section>.md` | Every page that shows the section without its own layout |
| A page block, for example `reviewsSection:` in a page file | That page only |

Set it in both language folders. Without a `layout` value, a section uses `default` (the logos use `grid`).

Copy the value from the comment next to `layout:` or from the catalog below. Section files have no schema, so `npm run astro-check` doesn't report a misspelled value there: open the page to check it. In page blocks of files with a schema (for example `homepage/english/home-cleaning.md`), `astro-check` reports a value that doesn't exist.

### Preview Every Layout: /elements/
<div class="border border-dark">
  ![The Homio layout gallery at /elements/ with the jump list of sections and layouts](/images/homio/elements.jpg)
</div>

Open `/elements/` on your site (`http://localhost:4321/elements/` with `npm run dev`). It shows every section in every layout, with the section's default content, so you can compare looks before you choose. A list at the top jumps to each section and each layout, and each preview names the value to copy. The page ends with the header and footer layouts and the page templates.

The gallery's copy is in `src/content/pages/english/elements.md` (and `french/`). The page is `noindex` and left out of the sitemap. Before launch, keep it as a private reference or delete `src/pages/[...lang]/elements.astro`, both `elements.md` files, and the **Elements** link in the **Pages** menu of `src/config/menu.en.json` and `menu.fr.json`.

<Aside type="note" title="The Change layout button">
  `[settings.layoutSwitcher] enable = true` in `config.toml` adds a floating
  **Change layout** button to the homepages and most inner pages, to try each
  layout on the real page. It is a demo feature and ships `false`. Keep it off on
  your live site: the button is for previewing, and it adds every other layout
  to the page as hidden markup.
</Aside>

### Layout Catalog
The values come from the `layoutOption([...])` lists in `src/sections.schema.ts`. The first value of each section is its default.

#### Hero
File: `hero-section.md` · Block: `heroSection`

| Layout | What it looks like |
| --- | --- |
| `default` | A framed photo with a sage card on one side (title, one line, two buttons, three check items), a sunflower price sticker, and the rating chip in a notch of the photo |
| `split` | A light mint panel with the copy, a call pill, and the main button, beside a photo that runs to the page edge with a white price card pinned to it |
| `form` | A framed photo band with a white card over its lower part holding a short quote form |
| `band` | A full-width photo under the header with the title in white on it, and an optional small photo card holding the main button |

`priceTag` sets the sticker (`default`) and the price card (`split`); `form` holds the quote form fields; `trades` adds the row of trade tiles with from-prices under the `default` and `band` heroes. The `band` hero sits under the `simple` header, which turns transparent over the photo, as on `/home-handyman/`.

#### Trust Strip
File: `trust-strip.md` · Block: `trustStrip`

| Layout | What it looks like |
| --- | --- |
| `default` | A deep green rounded block: the rating as a big number with stars, then each fact beside its icon, split by thin dividers |
| `badges` | A white card: the rating and each rating source on the first row, the facts on the second |
| `features` | A warm band with three facts, each with an icon in a small square, a short title, and one or two lines. No rating |

#### Services
File: `services-section.md` · Block: `servicesSection`

| Layout | What it looks like |
| --- | --- |
| `default` | Photo cards by trade, with the from-price of each |
| `list` | Grouped rows with duration, crew, and price, under sticky trade pills (the `/services/` page) |
| `trades` | One trade at a time, with a tab per trade |
| `cards` | Gradient frames with tilted photos and a "Learn more" pill per trade |
| `columns` | The intro split in two, then one column per service with an icon, split by thin lines |
| `overlay` | Tall photo cards with the trade name on the photo, and a centred button |
| `checklist` | A centred intro over a white card per service with check rows, then a green-bordered guarantee card (`customTile`) |

The trades, services, and prices come from `src/content/services/` and `src/content/pricing/`.

#### Steps
File: `steps-section.md` · Block: `stepsSection`

| Layout | What it looks like |
| --- | --- |
| `default` | One bold colour block per step with a huge number, the title, the text, and the `meta` line |
| `row` | A light row of three to five steps with big numbers, on thin lines |
| `timeline` | A sticky intro beside a schedule: a time column, a line with round nodes, and a photo per step |
| `illustrated` | Mint circles with line drawings (`illustration` per step), joined by arrows |
| `staggered` | Four cards that step down from left to right, each with a photo |
| `path` | Steps placed right, left, right along a dashed winding line, with the button under it |

#### Plans
File: `plans-section.md` · Block: `plansSection`

| Layout | What it looks like |
| --- | --- |
| `default` | Plan cards with the visit-frequency toggle |
| `hourly` | The trade rate sheet: rate, minimum, and note per service (ignores `plans`) |
| `table` | Every plan and frequency price at once, in one table, with no toggle |
| `savings` | Three sunflower tiles: the label and title in the middle, the first two recurring discounts beside it |

`/pricing/` shows `default` and, under it, a second plans block (`ratesSection`) in the `hourly` layout.

#### Add-Ons
File: `add-ons-section.md` · Block: `addOnsSection`

| Layout | What it looks like |
| --- | --- |
| `default` | Tiles, four per row on desktop |
| `list` | One list with the prices on the right |

#### What's Included
File: `included-section.md` · Block: `includedSection`

| Layout | What it looks like |
| --- | --- |
| `default` | A table with one column per service and one row per task, grouped by room |
| `rooms` | One tab per room |

#### Reviews
File: `reviews-section.md` · Block: `reviewsSection`

| Layout | What it looks like |
| --- | --- |
| `default` | The rating summary beside a lead review, over a two-column grid |
| `marquee` | A rating line, then rows of short reviews moving slowly in opposite directions (still, and scrollable, with reduced motion) |
| `wall` | A ratings table, a featured band, and a review wall with service filter buttons (the `/reviews/` page) |
| `summary` | The rating and the ratings per source beside three reviews |
| `carousel` | A sage panel with two review cards in view, round arrows, dots, and a rating chip in a tab |
| `spotlight` | A big counter and client logos, then one review at a time with a picker |
| `single` | One big card at a time with a photo, the stars, and the quote, with round arrows |
| `band` | A green block with a photo card (`photos`) and client `logos`, a rating tab, and review cards |

The reviews come from `src/content/reviews/`, and the rating figures from `trust-strip.md`. `spotlight` and `single` show a photo per review only when you add real portraits in `portraits`; never use placeholder faces. See [Reviews & Projects](/homio/customization/reviews-projects/).

#### Service Areas
File: `areas-section.md` · Block: `areasSection`

| Layout | What it looks like |
| --- | --- |
| `default` | Area pills and the ZIP code finder beside a neighbourhood photo |
| `list` | The finder on a band, then one card per area with its ZIP codes and neighbourhoods (the `/areas/` page) |
| `finder` | The intro beside the finder panel and its "All areas" list |
| `tabs` | One tab per area with its hours, address, phone, email, link, and photo |

#### Call To Action
File: `call-to-action.md` · Block: `ctaSection`

| Layout | What it looks like |
| --- | --- |
| `default` | With an `image`: the title, text, button, and phone beside a framed photo. Without one: a sunflower block with the same copy |
| `split` | Copy on the left and a recap card with the buttons and phone on the right (`ticket`) |
| `band` | A full-width brand-green band with a label, title, text, call pill, button, and photo |
| `newsletter` | Copy beside the email signup form (falls back to `default` when `[settings.subscription] enable = false`) |
| `slanted` | A deep green block with the photo at the bottom, its top edge cut at a slant |

The call to action ships off (`enable: false` in `call-to-action.md`). A page shows it with a `ctaSection` block that sets `enable: true`. See [Footer & CTA Band](/homio/customization/footer/).

#### FAQ
File: `questions-section.md` · Block: `questionsSection`

| Layout | What it looks like |
| --- | --- |
| `default` | A sticky intro and call box beside the accordion. With `group` on the questions and `groupNav: true`, a topic index with counts and a search box (the `/faq/` page) |
| `stacked` | The intro across the top, then one band per group of questions |
| `card` | A centred intro, then a warm side card beside the accordion |
| `grid` | A centred intro over two columns of outlined questions |

#### Feature Rows
File: `feature-grid-section.md` · Block: `featureGridSection`

| Layout | What it looks like |
| --- | --- |
| `default` | An icon grid, three or four columns (`columns`) |
| `alternating` | One row per item, the text and photo swapping sides on every other row |
| `tabs` | The item titles as tabs, with the active item's text and photo beside them |
| `sticky` | The intro and buttons stay in view while the items scroll past |
| `bento` | Bordered cells of mixed widths, each with an optional photo |
| `showcase` | A tall photo with a play button for `video`, and a second photo beside a green panel with two points |
| `split` | A photo on one half and a deep green panel with the title, points, and buttons on the other |
| `checks` | Check rows split by thin lines beside a large rounded photo |

#### Why Us
File: `why-us-section.md` · Block: `whyUsSection`

| Layout | What it looks like |
| --- | --- |
| `default` | A photo collage beside the benefits |
| `story` | A sage "who we are" panel over a green block with the benefit cards and the numbers from `metrics-section.md` (the main homepage) |
| `collage` | Two overlapping photos with a rotating circle of words, the opening hours, and a call button |
| `media` | A tall photo beside the copy, two short points, and a button |
| `accordion` | The copy, the benefits as rows that open, a button, and a photo |

#### Numbers
File: `metrics-section.md` · Block: `metricsSection`

| Layout | What it looks like |
| --- | --- |
| `default` | Three or four huge numbers with a bold label, counting up on scroll |
| `box` | The numbers in one warm box with thin dividers |

#### Before/After
File: `before-after-section.md` · Block: `beforeAfterSection`

| Layout | What it looks like |
| --- | --- |
| `default` | One large before/after slider (drag the line, or use the arrow keys) beside a project card with the service, area, and total |
| `grid` | A grid of project cards, with optional trade filter buttons (`filter`) and a large featured card (`featuredLarge`) |
| `gallery` | A masonry of job photos with a button. No sliders |

#### Contact
File: `contact-section.md` · Block: `contactSection`

| Layout | What it looks like |
| --- | --- |
| `default` | The open-now line, the phone as the headline, text, email, and office rows, the hours table, and the form (the `/contact/` page) |
| `walkthrough` | An intro and check rows (`benefits`) beside a form card, for commercial "request a walkthrough" pages |
| `quote` | A gradient form card beside a photo and a guarantee card (`guarantee`) |

#### Team
File: `team-grid-section.md` · Block: `teamGridSection`

| Layout | What it looks like |
| --- | --- |
| `default` | Roster cards from `src/content/team/` |
| `portraits` | A centred intro, then photo cards with the name and role. A member without a photo gets a card without one |

#### Logos
File: `clients.md` · Block: `clientsSection`

| Layout | What it looks like |
| --- | --- |
| `grid` | Logos in a grid of 4 or 6 per row (`columnsPerRow`) |
| `plain` | A borderless row of logos |

#### Booking Request
File: `booking-section.md` · Block: `bookingSection`

| Layout | What it looks like |
| --- | --- |
| `default` | The full five-step booking form (the `/book/` page) |
| `card` | A photo backdrop with a white card holding a photo, three numbers, and the first step. **Continue** opens `/book/` with the choice |

#### Blog Teaser
File: `related-posts-section.md` · Block: `relatedPostsSection`

| Layout | What it looks like |
| --- | --- |
| `default` | A lead post and rows |
| `side` | The intro and link button beside two posts |

#### Service Page Hero
File: `service-hero-section.md` · Set in each service: `options.layout` in `src/content/services/english/<service>.md`

| Layout | What it looks like |
| --- | --- |
| `default` | The service facts and a static price ticket |
| `cleaning` | The estimator in the hero, locked to this service |
| `repair` | The hourly rate block and a job list ticket, with a "Send your list" button |
| `commercial` | A site ticket and a "Request a walkthrough" button, with no booking and no total |

This value is more than a look: it picks the whole template of the service page and its section order. See [Services & What's Included](/homio/customization/services-included/).

#### Sections With One Layout
These have `layout: "default"` only, ready for more later: instant estimate (`estimate-section.md`), about hero, story, values, careers band, open roles, guarantee claim, credentials (`compliance-section.md`), contact options, not our job (`not-covered-section.md`), blog list, newsletter, and not found. The gift card and referral blocks have one layout too.

### Page Header
Inner pages open with a page header, set per page in a `pageHeader` block of the page file (there is no section file):

```yaml
# src/content/faq/english/-index.md
pageHeader:
  breadcrumb: true
  eyebrow: ""
  description: "Short answers about prices, the visit, your crew, and changes. Each one links to the detail."
  image: "/images/steps/book-on-phone-hands.jpg" # 4:3 photo on the right (`split`)
  options:
    layout: "split" # default | intro | centered | split
```

| Layout | What it looks like |
| --- | --- |
| `default` | The title and description on the left, short facts (the `summary`) on the right |
| `intro` | Compact: the title and description on the left, the buttons or phone line on the right (the `/book/` page) |
| `centered` | One narrow centred column, the facts as one line |
| `split` | The copy on the left and, on the right, a fact sheet: the `ticket`, else the `image` (with both, the ticket rows show as a card over the photo) |

The title comes from the page's `title`. The other fields are `breadcrumb`, `eyebrow`, `description`, `primaryButton`, `secondaryButton`, `buttons`, `badges`, `phone` (`style: "line"` or `"button"`), `summary`, `ticket`, `image`, and `imageAlt`. `options.compact: true` gives another layout the `intro` height.

### Header And Footer Layouts
The site header and footer have their own layouts, set in `[settings.layout]` of `config.toml`, or per page with `headerLayout` and `footerLayout` in the frontmatter:

```toml
[settings.layout]
  header = "default" # default | simple | centered | utility
  footer = "default" # default | minimal | large | columns
```

See [Header & Mobile Bar](/homio/customization/header/) and [Footer & CTA Band](/homio/customization/footer/).

### What The Homepages Use
The four homepages are the best showcase of the layouts. To reuse a look, copy the block (and any extra fields) from that homepage's file in `src/content/homepage/english/`.

| Section | `/` | `/home-cleaning/` | `/home-commercial/` | `/home-handyman/` |
| --- | --- | --- | --- | --- |
| Hero | `default` | `form` | `split` | `band` |
| Steps | `illustrated` | `path` | – | `staggered` |
| Why us | `story` | `accordion` | `collage` | `media` |
| Services | `cards` | `checklist` | `columns` | `overlay` |
| Reviews | `carousel` | `band` | `spotlight` | `single` |
| Contact | `quote` | – | `walkthrough` | – |
| FAQ | `default` | `grid` | – | `card` |
| Feature rows | – | `checks` | `showcase` | `split` |
| Other | – | plans `savings`, booking `card`, blog `side`, areas `tabs` | team `portraits`, CTA `band` | trust strip `features`, numbers `box`, before/after `gallery`, CTA `slanted` |

<Aside type="note">
  A layout that needs a field you haven't filled in still renders. For example,
  the `band` reviews without `photos` show no photo card. When you switch, copy
  the fields from the homepage that uses the layout.
</Aside>

### Do It With AI
```text
Switch the [SECTION] section to the [LAYOUT] layout [everywhere | only on PAGE URL]. Check the
allowed values in layoutOption([...]) in src/sections.schema.ts and the comment next to layout: in
src/content/sections/english/[FILE].md. If the layout uses extra fields, copy them from the
homepage file that already uses it. Change english/ and french/, then run npm run astro-check and
tell me which page to open to check it.
```