Sub Hero
The sub hero sits below the header on every content page and displays the page title and description. The flat variant removes the gradient background for pages where a neutral, image-free header is more appropriate.
Default
<section class="nds-hero-section nds-sub">
<nav class="nds-breadcrumb-nav" aria-label="Breadcrumb">
<ol class="nds-breadcrumb">
<li><a href="/">Home</a></li>
<li><a href="/parent">Parent Section</a></li>
<li aria-current="page">Current Page</li>
</ol>
</nav>
<div class="nds-section-wrapper">
<div class="nds-section-head">
<h1 class="nds-section-title">Service Portal</h1>
<p class="nds-section-description">Access government services, track applications, and manage your digital identity in one place.</p>
</div>
</div>
</section>
Flat
<section class="nds-hero-section nds-sub nds-flat">
<nav class="nds-breadcrumb-nav" aria-label="Breadcrumb">
<ol class="nds-breadcrumb">
<li><a href="/">Home</a></li>
<li><a href="/parent">Parent Section</a></li>
<li aria-current="page">Current Page</li>
</ol>
</nav>
<div class="nds-section-wrapper">
<div class="nds-section-head">
<div class="nds-section-action nds-minimal">
<div class="nds-share nds-dropmenu">
<button class="nds-btn nds-secondary-outline nds-dropmenu-trigger" aria-label="Share Page">
<i class="nds-icon nds-hgi-share-01" aria-hidden="true"></i>
<span class="nds-label">Share Page</span>
</button>
<div class="nds-dropmenu-menu" hidden>
<button class="nds-btn nds-subtle nds-dropmenu-item nds-share-x" type="button" aria-label="Share on X">
<i class="nds-icon nds-hgi-new-twitter" aria-hidden="true"></i>
<span class="nds-label">X</span>
</button>
<button class="nds-btn nds-subtle nds-dropmenu-item nds-share-linkedin" type="button" aria-label="Share on LinkedIn">
<i class="nds-icon nds-hgi-linkedin-02" aria-hidden="true"></i>
<span class="nds-label">LinkedIn</span>
</button>
<button class="nds-btn nds-subtle nds-dropmenu-item nds-share-whatsapp" type="button" aria-label="Share on WhatsApp">
<i class="nds-icon nds-hgi-whatsapp" aria-hidden="true"></i>
<span class="nds-label">WhatsApp</span>
</button>
<button class="nds-btn nds-subtle nds-dropmenu-item nds-share-copy" type="button" aria-label="Copy Link"
data-label="Link Copied!" data-message="Page link copied to clipboard" data-no-auto-close>
<i class="nds-icon nds-hgi-link-04" aria-hidden="true"></i>
<span class="nds-label">Copy Link</span>
</button>
</div>
</div>
</div>
<h1 class="nds-section-title">Service Portal</h1>
<p class="nds-section-description">Access government services, track applications, and manage your digital identity in one place.</p>
</div>
</div>
</section>
With Brief
<section class="nds-hero-section nds-sub">
<nav class="nds-breadcrumb-nav" aria-label="Breadcrumb">
<ol class="nds-breadcrumb">
<li><a href="/">Home</a></li>
<li><a href="/parent">Parent Section</a></li>
<li aria-current="page">Digital Identity</li>
</ol>
</nav>
<div class="nds-section-wrapper">
<div class="nds-section-head">
<h1 class="nds-section-title">Digital Identity</h1>
<p class="nds-section-brief">Your unified gateway to all government services</p>
<p class="nds-section-description">Manage your national ID, verify documents, and access personalized services from a single secure account linked to your identity.</p>
</div>
</div>
</section>
With Background Image
Set the --hero_image CSS custom property to place a branded photograph behind the sub hero. A CSS mask fades the image from the start edge toward the content area — the background color shows through where the image fades out, so the fade adapts automatically to any theme or color token.
With Background Image
<section class="nds-hero-section nds-sub" style="--hero_image: url('assets/img/hero.webp')">
<nav class="nds-breadcrumb-nav" aria-label="Breadcrumb">
<ol class="nds-breadcrumb">
<li><a href="/">Home</a></li>
<li><a href="/parent">Parent Section</a></li>
<li aria-current="page">Current Page</li>
</ol>
</nav>
<div class="nds-section-wrapper">
<div class="nds-section-head">
<h1 class="nds-section-title">About the Authority</h1>
<p class="nds-section-description">The Digital Government Authority leads digital transformation across Saudi government services and establishes national standards.</p>
</div>
</div>
</section>
Sub Hero with Actions
The sub hero provides two action slots: a float action placed inline-end inside the heading area for contextual tools such as share or bookmark, and a standard action block below the description for primary calls-to-action.
With Actions
<section class="nds-hero-section nds-sub">
<nav class="nds-breadcrumb-nav" aria-label="Breadcrumb">
<ol class="nds-breadcrumb">
<li><a href="/">Home</a></li>
<li><a href="/services">Services</a></li>
<li aria-current="page">Digital Services Portal</li>
</ol>
</nav>
<div class="nds-section-wrapper">
<div class="nds-section-head">
<!-- Float action: appears inline-end inside the heading area -->
<div class="nds-section-action">
<a class="nds-btn nds-secondary-outline" href="/help">
<span class="nds-label">Help Center</span>
</a>
</div>
<h1 class="nds-section-title">Digital Services Portal</h1>
<p class="nds-section-description">Browse and apply for government services from one centralized portal available around the clock.</p>
</div>
<!-- Standard action: appears below the description -->
<div class="nds-section-action">
<a class="nds-btn nds-primary" href="/services">
<span class="nds-label">Browse Services</span>
</a>
<a class="nds-btn nds-secondary-outline" href="/about">
<span class="nds-label">Learn More</span>
</a>
</div>
</div>
</section>
Main Hero Slider
The main hero is a full-viewport-height banner used on home and hub pages. It wraps a Swiper carousel so multiple slides can rotate with pagination controls. Each slide has its own background image, overlay opacity, and content area.
Main Hero Slider
Built-in Features
Background Image Support
Set --hero_image on the sub hero to place a branded photograph behind the gradient with no additional markup.
CSS Mask Image Fade
A CSS mask fades the background image to transparent on the content side so the page background color shows through — no gradient color matching needed when the theme or background token changes.
Flat Variant
Add nds-flat to switch to a plain page background with no gradient, suited for utility and documentation pages.
Aside Layout Mode
Add nds-aside to narrow the hero content area to leave room for a Side Info panel sitting alongside on desktop.
Dual Action Slots
The sub hero has a float action slot inside the heading for contextual tools and a standard action slot below the description for primary calls-to-action.
Bidirectional Mask
The mask fade direction flips automatically between RTL (Arabic) and LTR (English), so the image always appears on the correct edge and text remains readable in both directions.
Usage Guidelines
Best Practices
- Use the sub hero on every content page as the primary title area. Pair it with the Header for complete shell structure
- Reserve the main hero slider for home pages and top-level hub pages. It occupies 60% of the viewport height and is inappropriate for deep content pages
- Use
nds-flaton pages where a gradient or brand-colored header would feel heavy, such as documentation pages, search results, and admin interfaces - Use
nds-asideonly when the page layout also includes a Side Info panel. Without the panel, the narrowed content area looks unbalanced - Keep sub hero descriptions to one or two sentences. The hero is an orientation area, not a content section
- Add action buttons sparingly. One or two calls-to-action in the standard slot is enough. Overcrowding the hero with buttons competes with the page content below
- For main hero slides, use the float action slot (such as a share button) for tools rather than navigation. Visitors who arrived on the page are past the "where to go" decision
- Background images on the sub hero should have a clear subject on the start edge (right in RTL, left in LTR) — the mask keeps that edge fully opaque while fading toward the content area
- Set
fetchpriority="high"on the first main hero slide image. It is the Largest Contentful Paint element on home pages and skipping this degrades Core Web Vitals scores - Preload that same first slide image in the page
<head>, one<link rel="preload" as="image">per breakpoint. The image sits in a<picture>deep in the body, so the browser finds it late and the download starts after the page parses. Repeat themediaconditions from the slide's<source>elements exactly, or the browser preloads one file and then paints another. The preload is page-specific: each page preloads its own hero image, and a page with no hero image carries none of these lines. See Head for the block to copy - Use
data-srcon second and later main hero slides to defer image loading until the slide is about to appear. Adddata-srcseton their<source>elements too — a plainsrcsetthere loads straight away and the deferral is lost - The canonical main hero carries a photograph. If you do not have one yet, keep the
<picture>and point it at a placeholder image, then replace the file later. A hero with no image is a design choice the project makes on purpose, not the shape to fall back to when an image file is missing - Leave
--img-overlay-coloralone. It already carries the brand surface color and follows a brand re-tint on its own. Setting it by hand replaces a themeable token with a fixed value, and that hero then stops following the theme - Do not use
nds-flaton a main hero. It is a sub hero class and does nothing here - Adjust
--overlayper slide on the main hero to match each image's brightness. Dark images need lower values (0.4-0.5), bright outdoor images need higher values (0.6-0.8)
Modifier Classes
| Class | Applied To | Description |
|---|---|---|
nds-sub |
.nds-hero-section |
Compact sub-page variant with gradient background, fit-content height, and reduced typography scale |
nds-flat |
.nds-hero-section.nds-sub |
Removes the gradient and brand background, rendering the hero on the standard page background color. Sub hero only: the rule is scoped to .nds-sub, so the class has no effect on the main hero slider. Text inside a flat hero must not carry nds-oncolor, which would render white on white |
nds-aside |
.nds-hero-section.nds-sub |
Narrows the hero content area at desktop width to leave room for a Side Info panel alongside |
CSS Custom Properties
| Property | Default | Description |
|---|---|---|
--hero_image |
none | Background image URL for the sub hero. Set as an inline style: style="--hero_image: url('...')". The CSS mask fades it automatically. |
--hero-mask-angle |
90deg RTL / 270deg LTR |
Direction of the mask gradient. Auto-set per text direction; override with a fixed angle for a top-to-bottom or diagonal fade. |
--hero-mask-from |
0% |
Start position of the fully opaque image edge. Increase to push the visible area inward from the start edge. |
--hero-mask-to |
70% |
Point at which the image fully fades out. Decrease for a sharper cut, increase to reveal more of the image behind the content area. |
--overlay |
0.7 |
Opacity of the dark overlay on the main hero image wrapper. Set on .nds-hero-image-wrapper via inline style. Range: 0 (transparent) to 1 (fully opaque). |
--img-overlay-color |
--colors-primary-950 |
Color of that overlay. It is a global token that already follows the active brand, so leave it at its default. Override it on the wrapper only to recolor one slide against the brand, and expect that slide to stay fixed while the rest of the theme changes. |