# Hero

Shows a hero banner on the top of the page. The section supports a background image with an overlay to improve contrast. The hero includes a headline and optional breadcrumb for site navigation.

## Overview

### Basic hero

The `hero` content block renders a page hero, typically at the top of the page. Set `cover` to true to display a full-page hero.

```yml
- _bookshop_name: hero
  heading:
    title: Title
    align: start
    content: Hero content
    width: 12
```

### Illustrated hero

You can include an `illustration` next to the hero heading. Specify `orientation` and `order` to configure the illustration's placement. You can set `cover` to true to display a full-height hero. In horizontal layout, `heading.width` sets how many Bootstrap columns the heading occupies (1–12); the illustration fills the remaining columns. Use `illustration.width` to further constrain the image within its column (1–12).

```yml
- _bookshop_name: hero
  background:
    color: body-tertiary
    subtle: false
  heading:
    title: Title
    align: start
    content: Hero content
    width: 8
  orientation: horizontal
  order: last
  illustration:
    image: /img/placeholder.png
    ratio: 1x1
```

### Image sizing

Use `illustration.width` to constrain the image within its column. In the example below,
`heading.width: 8` allocates 8 columns to the heading (leaving 4 for the illustration), and
`illustration.width: 10` renders the image at 10/12 of that 4-column container.

```yml
- _bookshop_name: hero
  heading:
    title: Title
    align: start
    content: Hero content
    width: 8
  orientation: horizontal
  order: last
  illustration:
    image: /img/placeholder.png
    ratio: 3x2
    width: 10
```

### Hero with breadcrumb

Set `breadcrumb` to `true` to add a breadcrumb to the top of the hero.

```yml
- _bookshop_name: hero
  heading:
    title: Title
    align: start
    content: Hero content
    width: 12
  breadcrumb: true
```

### Hero with backdrop

Adjust the background of the hero by configuring a `backdrop` that links to an image asset.

```yml
- _bookshop_name: hero
  heading:
    title: Title
    align: start
    content: Hero content
    width: 12
  background:
    backdrop: /assets/img/logan-voss-dAo9K7PG1kQ-unsplash.jpg
  breadcrumb: true
```

## Arguments

The content block supports the following arguments:

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `align` | select |  | `start` | Alignment of the headline, content, or icon. Supported values: [`start`, `center`, `end`]. |
| `background` | background |  |  | Background style of the section. |
| `bg-class` | string |  |  | Background class attributes of the element. It supports Bootstrap attributes to modify the background styling of the element. |
| `breadcrumb` | bool |  |  | Flag to include a breadcrumb in the element. |
| `cover` | bool |  |  | Flag indicating if the element should be rendered fullscreen. |
| `fluid` | bool |  | `true` | Flag to set the section container to fluid design, else the section is limited to `xxl`. |
| `heading` | heading |  |  | Heading of the content block, including a preheading and content element. |
| `illustration` | illustration |  |  | Featured illustration of the element. |
| `justify` | select |  | `start` | Justification of the child elements. Supported values: [`start`, `end`, `center`, `between`, `around`, `evenly`]. |
| `link-type` | select |  | `button` | Style of the link. Supported values: [`button`, `link`]. |
| `links` | links |  |  | Links to add as buttons. |
| `order` | select |  | `last` | Order of the illustration. Supported values: [`first`, `last`]. |
| `orientation` | select |  | `stacked` | Placement of the thumbnail or icon. Supported values: [`stacked`, `horizontal`, `horizontal-sm`, `overlay`, `none`]. |
| `overlay-mode` | select |  |  | Overlay mode of the element, overrides the site's general configuration. Supported values: [`light`, `dark`, `none`]. |
| `section-class` | string |  |  | Section class attributes of the element. It supports Bootstrap attributes to modify the section styling of the element. |
| `theme` | select |  |  | Color theme to apply to the element. Supported values: [`light`, `dark`]. |
| `width` | int |  | `8` | Column width of the element. For embedded elements, the width is relative to the parent's container. |
| `wrapper` | string |  |  | Class attribute of the element's wrapper. It supports Bootstrap attributes to modify the styling of the element. Icons include the `fa-wrapper` and `fa-fluid` attributes by default. |