The Hero component displays a full-width background image with a title overlaid on a dark gradient, and a short accent-coloured underline below the title.
The hero renders outside <main> via a named slot in BaseLayout, so it spans
the full viewport width regardless of content width settings.
---
import BaseLayout from "astro-theme-university/layouts/BaseLayout.astro";
import Hero from "astro-theme-university/components/Hero.astro";
import bannerImage from "../assets/images/banner.avif";
---
<BaseLayout title="Home">
<Hero
slot="hero"
title="Research & Innovation"
image={bannerImage}
imageAlt="Researchers at work in a laboratory"
/>
<p>Page content here.</p>
</BaseLayout>
The image prop accepts an imported image (ImageMetadata), processed through
Astro’s image pipeline for optimisation, or a RemoteImage object
({ src, width?, height?, srcset?, sizes? }) for a pre-encoded external source
— a CDN or object-store URL — rendered as a plain <img> with no build-time
processing.
Props#
| Prop | Type | Default | Description |
|---|---|---|---|
title * | string | --- | The hero heading text, rendered as an h1. |
image * | ImageMetadata | RemoteImage | --- | Hero background image. Pass an imported image for pipeline optimisation, or a `RemoteImage` for a pre-encoded external source rendered as a plain `<img>`. |
imageAlt * | string | --- | Alt text for the hero image. Describes the image for screen reader users. |
imageWidths | number[] | [768, 1536, 2560] | Srcset widths (px) for the hero image. The default covers full-bleed display up to 2x DPR. |
imageSizes | string | "100vw" | The `sizes` attribute paired with the srcset. The default matches the hero's full-bleed layout. |
imageFormat | ImageOutputFormat | themeImageFormat | Output format for the hero image. Defaults to the `imageFormat` integration option, itself `"webp"` unless the site opts into something else. Ignored for an SVG source, which is always passed through unrasterised. |
transitionName | string | --- | View transition name for the heading element. |
Usage#
Use slot="hero" to place the Hero in the BaseLayout’s hero slot, between the
navigation and main content area.
---
import campusImage from "../assets/images/campus.avif";
---
<BaseLayout title="News">
<Hero
slot="hero"
title="Latest news"
image={campusImage}
imageAlt="University campus at sunset"
/>
<!-- page content -->
</BaseLayout>
Using the hero from MDX pages#
MDX pages can’t use named slots. To pass an imported image, wrap the content in
the layout component directly instead of using the layout frontmatter field:
import PageLayout from "../layouts/PageLayout.astro";
import heroImage from "../assets/images/campus.avif";
<PageLayout title="News" heroTitle="Latest news" heroImage={heroImage}>
Page content as markdown.
</PageLayout>
See the BaseLayout docs for details.
Notes#
- The title is always rendered in white against the dark gradient overlay, regardless of the current light/dark theme setting.
- The accent underline uses the
--at-primarybrand colour and is not affected by theme changes. - For best results, use landscape images at least 1600px wide. The image
displays with
object-fit: cover, so it crops to fill the banner area. - The hero title text is constrained to
--at-content-widthso it aligns with the page content below.