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

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.

Top Bar Widgets

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. City is reverse-geocoded via the Nominatim API (30-day cache), 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 share coordinates and 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

Reverse-geocoded city name pairs with live weather readings from Open-Meteo. 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.
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-calendar`	`#nds-date`	Set to `hijri` or `gregorian`. Defaults to Hijri for Arabic pages.
`data-latitude` / `data-longitude`	`#nds-weatherInfo`	GPS coordinates for weather and city lookup. Defaults to Riyadh (24.7136, 46.6753).

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 ────────────────────────
// Opens or closes the digital stamp panel.
// Automatically closes the navbar or open dropdowns
// first to prevent overlapping panels.
window.toggleDGA();

// ── 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

Cookies