Attributes
All attributes are optional and can be combined freely. Changing any of them at runtime (e.g. via Javascript) re-renders the component.
| Attribute | Values | Description |
|---|---|---|
type | split (default), hero | Chooses the layout template. split places content and media side by side, hero layers content over a media background. Combine with media="fluid" (see below) for that background to bleed to the viewport. Without it, hero or split just fill their parent container. |
media | fluid | Lets the media section stretch to the edge of the viewport (beyond its parent container) while content stays within it. |
order | flip | Reverses the order of the content and media sections when type="split". |
overlay | true | type="hero" only. Forces the content to always overlay the media, even below --steam-block-min-width-breakpoint where it would otherwise stack on top like the split template. Use this to opt out of the default mobile stacking behavior. The media aspect ratio then works as a minimum at every width, the hero grows when the content needs more room, see below. |
prefix | any string | Overrides the CSS variable prefix. Defaults to steam-block-, so --steam-block-background becomes --<prefix>background. |
emerge | true | Hooks the element into steam-emerge.js so it gains an emerge class when scrolled into view, or whatever class emerge-class names instead. See Helpers. Requires steam-emerge.js to be loaded first. |
<steam-block type="hero" media="fluid" order="flip" overlay="true" prefix="hero-" emerge="true">
...
</steam-block>
Why media="fluid" breaks out of any layout
The common way to bleed a section to the viewport edge is margin-inline: calc(50% - 50vw). It works, but only because it assumes the section is already centered in a plain, symmetric container. Put that same section inside a CSS Grid column, a sidebar layout, or anything else off-center, and the math is wrong, since 50vw has no idea where the element actually landed on screen.
media="fluid" doesn’t make that assumption. It measures the element’s real, rendered position (getBoundingClientRect()) and computes the breakout from that, not from a fixed percentage. That’s why the duotone hero on the Usage page bleeds to the true viewport edge correctly even though this documentation layout renders it inside a narrower sidebar column: it doesn’t need the container to be symmetric, or centered, or even aware that a breakout is happening.
The aspect ratio is a minimum
An overlaid heading, paragraph and button don’t always fit a fixed --<prefix>media-aspect-ratio, especially with copy from a CMS that you can’t foresee. Wherever the content overlays the media, at and above the breakpoint and at every width with overlay="true", the ratio works as a minimum. The hero keeps it as long as the content fits and grows taller when the content needs more room, with the media stretching along. Nothing is clipped, and no attribute is needed for it.
A short caption, like the overlay tiles in the homepage’s CSS variable showcase, keeps its exact ratio. Stacked below the breakpoint without overlay="true", the content sits under the media, so the media keeps its ratio there too.
An <iframe>such as a YouTube player can’t crop to fill like an image or video can. In a hero that grew taller than its ratio, the player shows its own black bars.