Top Bar

A slim utility bar above the main navigation that holds the DGA digital stamp trigger, date and time widgets, and a dark mode toggle.

Top Bar


<div class="nds-topbar nds-content-wrapper" role="region" aria-label="Top bar utilities">
  <button class="nds-btn nds-menu-btn nds-topbar-info nds-digitalStamp-tab"
      role="button" aria-expanded="false" aria-controls="nds-digitalStamp">
    <img class="nds-flag" src="flag.svg" width="20" height="14" loading="lazy" alt="Saudi Arabia Flag">
    <span class="nds-digitalStamp-lg-text nds-truncate">A government website registered with the Digital Government Authority.</span>
    <span class="nds-digitalStamp-sm-text nds-truncate">Government website registered with DGA</span>
    <span id="nds-digitalStamp-verify-text" class="nds-link nds-primary">How you know?</span>
  </button>
  <div class="nds-topbar-info">
    <span id="nds-date" class="nds-text-icon" data-calendar="hijri" data-hidden="sm md"></span>
    <span id="nds-realTimeClock" class="nds-text-icon" data-hidden="sm"></span>
    <span id="nds-cityName" class="nds-text-icon" data-hidden="sm md"
        data-city="الرياض" data-city-en="Riyadh"></span>
    <span id="nds-weatherInfo" class="nds-text-icon" data-hidden="sm"
        data-latitude="24.7136" data-longitude="46.6753"></span>
    <button class="nds-btn nds-subtle nds-theme-toggle-wrap" data-theme-toggle aria-label="Toggle dark mode">
      <i class="nds-icon nds-hgi-moon-02" aria-hidden="true"></i>
    </button>
  </div>
</div>

Top Bar Widgets

Three optional widgets for the top bar: date, clock, and city/weather. Each initializes automatically when its element IDs are on the page. DGA compliance permits a maximum of two: choose the combination that best serves your audience. You also choose where each widget hides on smaller screens by stamping data-hidden on it

Top Bar Widgets


<!-- Hijri or Gregorian date (set via data-calendar);
     data-hidden picks where the widget hides (here: 960px and below) -->
<span id="nds-date" class="nds-text-icon" data-calendar="hijri" data-hidden="sm md"></span>

<!-- Real-time clock (updates every second); hidden on mobile -->
<span id="nds-realTimeClock" class="nds-text-icon" data-hidden="sm"></span>

<!-- City & Weather (both required; city via data-city, coordinates on weatherInfo) -->
<span id="nds-cityName" class="nds-text-icon" data-hidden="sm md"
    data-city="الرياض" data-city-en="Riyadh"></span>
<span id="nds-weatherInfo" class="nds-text-icon" data-hidden="sm"
    data-latitude="24.7136" data-longitude="46.6753"></span>

Widget Reference

Element ID	JS Module	Description
`#nds-date`	`NDS.TimeDate`	Displays the current date. Set `data-calendar="hijri"` for the Islamic calendar or `data-calendar="gregorian"` for the Gregorian calendar. Fetches Hijri dates from the Aladhan API with a 24-hour local cache. Defaults to Hijri for Arabic pages and Gregorian for English.
`#nds-realTimeClock`	`NDS.TimeDate`	Live clock that updates every second in 12-hour AM/PM format.
`#nds-cityName` + `#nds-weatherInfo`	`NDS.CityWeather`	Displays the city name and current weather side by side. Set the city directly with `data-city` (and `data-city-en` for the English variant) on `#nds-cityName` — recommended, as it avoids a third-party call. Without it, the city is reverse-geocoded via the Nominatim API (30-day cache) as a fallback. Weather is fetched from Open-Meteo (15-minute cache); set `data-latitude` and `data-longitude` on `#nds-weatherInfo` to configure the location (defaults to Riyadh). Both elements must be present: they initialize together as a single widget.

DGA Digital Stamp

An expandable panel triggered from the top bar that verifies the site as an official Saudi government digital property. Displays domain verification and HTTPS security notices alongside the DGA registration number.

DGA Digital Stamp Panel


<div id="nds-digitalStamp" role="region" aria-label="Digital government stamp" hidden>
  <div class="nds-content-wrapper">
    <div class="nds-digitalStamp-notices">
      <!-- Domain Verification Notice -->
      <div class="nds-digitalStamp-card">
        <div class="nds-digitalStamp-icon">
          <i class="nds-icon nds-hgi-link-04" aria-hidden="true"></i>
        </div>
        <div class="nds-digitalStamp-content">
          <div class="nds-digitalStamp-heading">
            Official Saudi Government website URL ends with <span class="nds-digitalStamp-highlight">gov.sa</span>
          </div>
          <div class="nds-digitalStamp-description">
            Website belongs to an official government organization in the Kingdom of Saudi Arabia always ends with .gov.sa .
          </div>
        </div>
      </div>
      <!-- HTTPS Security Notice -->
      <div class="nds-digitalStamp-card">
        <div class="nds-digitalStamp-icon">
          <i class="nds-icon nds-hgi-square-lock-01" aria-hidden="true"></i>
        </div>
        <div class="nds-digitalStamp-content">
          <div class="nds-digitalStamp-heading">
            Official Secure websites use <span class="nds-digitalStamp-highlight">HTTPS</span>
          </div>
          <div class="nds-digitalStamp-description">
            Secured governments websites in the Kingdom of Saudi Arabia use Https encryption.
          </div>
        </div>
      </div>
    </div>
    <!-- DGA Registration -->
    <div class="nds-digitalStamp-register">
      <img src="dga-logo-icon.svg" width="21" height="31" alt="Digital Government Authority" loading="lazy">
      <div>
        <span>Registered on Digital Government Authority: </span>
        <a class="nds-digitalStamp-registration nds-primary nds-underline"
            href="#"
            target="_blank">00000000000</a>
      </div>
    </div>
  </div>
</div>

Built-in Features

Auto-initialization

Widgets, the DGA stamp toggle, and the theme switch all activate as soon as their elements are on the page. No manual wiring required.

DGA Stamp Toggle

The top bar button expands and collapses the digital stamp panel with animated grid-row transitions, automatically closing any open nav menus first.

Live Date & Clock

Date refreshes every 24 hours, the real-time clock ticks every second, and both switch language with the page to keep the surface aligned with user locale.

Hijri & Gregorian Calendars

The date widget supports both calendars via data-calendar. Hijri values come from the Aladhan API with a browser Intl fallback when offline.

City & Weather Widgets

An author-set city name (data-city) pairs with live weather readings from Open-Meteo, or falls back to a Nominatim reverse-geocode. City and coordinates are configurable per page via data attributes.

Local Caching

Hijri dates cache for 24 hours, weather for 15 minutes, and city names for 30 days, reducing API calls and keeping the top bar responsive across page loads.

Usage Guidelines

Best Practices

Include the DGA digital stamp on all government websites. The top bar trigger and hidden panel are mandatory for DGA compliance. Populate the registration number and notice text from site configuration.
DGA compliance allows a maximum of two top bar widgets. Choose any two from: date, clock, or city/weather.
Pair the clock with the date when the service is time-sensitive (appointments, deadlines, submissions). Pair the date with city/weather on portals where users need general awareness (citizen services, public dashboards).
Set data-calendar="hijri" on the date widget for Arabic audiences and Saudi government properties. Leave it at the default for English-only international-facing services.
Always set explicit data-latitude and data-longitude on the weather widget. Do not rely on the Riyadh default for services that target a specific city or region.
Set data-city (and data-city-en) on #nds-cityName so the city renders without a third-party geocode. The Nominatim fallback is rate-limited and not intended for per-visitor traffic at scale.
Stamp data-hidden on every data widget so the bar degrades deliberately on small screens. The recommended defaults: date and city hide at "mobile tablet", clock and weather at "mobile". Widgets without it stay visible at every width and can crowd the DGA stamp on phones.
Do not remove the theme toggle. Dark mode is part of the NDS accessibility baseline.
Do not add custom buttons to the top bar. Utility actions belong in the navigation bar's secondary actions area, which persists across all breakpoints.
Keep the nds-digitalStamp-lg-text verification copy short. Long text truncates on tablet before switching to the nds-digitalStamp-sm-text fallback.

Modifier Classes

Class	Element	Description
`nds-digitalStamp-tab`	top bar button	Styles the DGA stamp trigger with flag icon and verification text
`nds-digitalStamp-lg-text`	inside stamp tab	Full-length label shown on desktop, hidden on tablet and below
`nds-digitalStamp-sm-text`	inside stamp tab	Short label shown on tablet and below, hidden on desktop
`nds-topbar-info`	container	Groups the DGA tab contents and the right-side widget cluster

Data Attributes

Attribute	Element	Description
`data-theme-toggle`	top bar button	Registers the element as a dark/light mode toggle
`data-hidden`	any widget	Hides the widget inside the named viewport range: `mobile` (600px and below), `tablet` (601 to 960px), `desktop` (961 to 1280px), space-separated to combine. See the Hidden utility. An unstamped widget stays visible at every width
`data-calendar`	`#nds-date`	Set to `hijri` or `gregorian`. Defaults to Hijri for Arabic pages.
`data-latitude` / `data-longitude`	`#nds-weatherInfo`	GPS coordinates for the weather lookup. Defaults to Riyadh (24.7136, 46.6753).
`data-city` / `data-city-en`	`#nds-cityName`	City name shown in the widget (`data-city-en` is the English variant). Recommended — when set, the city renders directly with no network call; otherwise it falls back to a Nominatim reverse-geocode of the coordinates.

JavaScript API

The top bar widgets initialize automatically when their element IDs exist on the page. Use these APIs to re-initialize after dynamic content changes, refresh individual widgets manually, or pull Hijri dates programmatically for use elsewhere.


// ── Widget Re-initialization ────────────────
// Each module initializes automatically when its
// element IDs are on the page. Call these after
// dynamically adding widget markup.

// Re-initialize date and clock widgets
NDS.TimeDate.init();

// Re-initialize city and weather widgets
NDS.CityWeather.init();

// ── Manual Refresh ──────────────────────────
NDS.TimeDate.updateDate();        // refresh date display
NDS.TimeDate.updateClock();       // refresh clock display
NDS.CityWeather.updateWeather();  // re-fetch weather data
NDS.CityWeather.updateCity();     // re-fetch city name

// ── DGA Stamp Toggle ────────────────────────
// Standalone component — opens/closes the digital
// stamp panel. Opening it (or the nav) closes the
// other automatically via each surface's own
// outside-click handling.
NDS.DigitalStamp.toggle();   // also: .open(), .close(), .isOpen()

// ── Hijri Date API ──────────────────────────
// Pass true for Arabic, false for English.
// Cached for 24 hours, falls back to browser Intl
// if the Aladhan API is unreachable.
const hijriDate = await NDS.TimeDate.getHijriDate(true);

// Get structured Hijri data (day, month, year numbers)
const hijriData = await NDS.TimeDate.getHijriDate(true, true);
// Returns: { day: 15, month: 10, year: 1447 }

Top Bar - National Design System

Top Bar

Top Bar Widgets

Widget Reference

DGA Digital Stamp

Built-in Features

Usage Guidelines

Best Practices

Modifier Classes

Data Attributes

JavaScript API