Expandable Content - National Design System

Height-constrained containers that reveal additional content on demand, with automatic overflow detection and a toggle button that appears only when content exceeds the limit

Standard Expandable Content

Wraps any block of content in a height-constrained container. A "Show More" button appears automatically when the content overflows.

Basic Expandable Content

The National Digital Transformation Strategy outlines a comprehensive framework for modernizing government services across all sectors. The initiative focuses on three core pillars: citizen experience, operational efficiency, and data-driven decision making.

All government entities are required to adopt the unified design system for public-facing digital platforms. This ensures a consistent and accessible experience for citizens regardless of which ministry or agency they interact with. The system supports both Arabic and English interfaces with full right-to-left layout compliance.

Integration with the national identity platform enables single sign-on across all digital services. Citizens authenticate once and gain access to their complete service portfolio, including document requests, permit applications, appointment scheduling, and payment processing.

Accessibility standards follow international WCAG 2.1 AA guidelines adapted for the Arabic language context. All components are tested for screen reader compatibility, keyboard navigation, color contrast compliance, and support for reduced motion preferences.

Performance benchmarks require all pages to achieve a Lighthouse score of 90 or above. This includes optimized asset delivery, lazy loading for below-the-fold content, and efficient caching strategies for frequently accessed service endpoints.

Expandable Card

Apply expandable behavior directly to a card component to constrain long descriptions or detail blocks within a defined height

Ministry Services Documentation

Complete documentation and guidelines for all ministry digital services including API references, implementation guides, best practices for developers, integration specifications, security protocols, and compliance requirements for government applications. This comprehensive resource covers everything from basic setup to advanced configurations.

Sibling Sync

Wrap multiple expandable containers in an nds-expand-all parent so expanding or collapsing one toggles all siblings in sync

Synchronized Expandable Containers

Digital Identity Standards

Comprehensive guidelines for implementing digital identity verification across government platforms, including biometric authentication protocols, single sign-on integration, and multi-factor authentication requirements for all public-facing services.

Data Classification Policy

Standards for categorizing, handling, and protecting government data assets including classification levels, access control matrices, encryption requirements, and retention schedules for sensitive and public information.

Built-in Features

Auto-initialization

Activates on every .nds-expandable element at page load. The toggle button is added only when the content actually overflows.

Responsive Height Detection

Continuously monitors content size and shows or hides the toggle button when the viewport or container dimensions change.

Gradient Fade Indicator

A configurable gradient mask fades the bottom of truncated content, signaling that more content is available below.

Bilingual Labels

The toggle button label switches between English ("Show More" / "Show Less") and Arabic automatically based on the page language.

Sibling Sync

Wrap multiple expandable containers in an nds-expand-all parent and expanding one will expand all siblings together.

Programmatic Control

Expand, collapse, toggle, and query state through instance methods on element.ndsExpandable.

Usage Guidelines

Best Practices

  • Use expandable content to keep pages scannable when a section contains long descriptions, legal text, detailed specifications, or extended lists that most users will not need to read in full
  • Use inside Cards to constrain card body height while still exposing a preview of the full content
  • Use the nds-expand-all wrapper when multiple related items should reveal their content together, such as a comparison grid or a set of policy summaries
  • Do not use expandable content for short text that fits within the default 300px limit. The toggle button will not appear, but the extra wrapper adds unnecessary DOM weight
  • Do not use expandable content to hide primary actions or critical information the user must see. Use an Accordion for structured show/hide sections with headings
  • Set --max-height to a value that shows enough content for the user to judge whether they want to read more. Avoid values below 80px as they may obscure the first paragraph entirely
  • When adding expandable content to dynamically loaded elements, call NDS.Expandable.reinit() after inserting the new HTML to initialize the new containers
  • Place --max-height on the .nds-expandable-content element (not the outer wrapper) when the expandable container has its own padding or borders that should remain visible
  • Use recheckHeight() or NDS.Expandable.recheckHeights() after content changes (AJAX loads, tab switches) to re-evaluate whether the toggle button is still needed

CSS Custom Properties

PropertyDefaultDescription
--max-height300pxMaximum visible height before the content is clipped and the toggle button appears. Set on .nds-expandable or .nds-expandable-content
--mask-fade-percentage35%Percentage of the content height that fades to transparent when collapsed. Higher values create a longer gradient

JavaScript API

The NDS.Expandable API provides methods to initialize containers, control expand/collapse state, and listen for state change events. Instances are accessible via element.ndsExpandable.

// ── Initialize manually ───────────────────────────── // Useful for content added after page load const container = document.querySelector('#myExpandable'); const instance = NDS.Expandable.create(container); // Re-scan the page for new .nds-expandable elements NDS.Expandable.reinit(); // Recheck all initialized containers (after AJAX, tab switch, etc.) NDS.Expandable.recheckHeights(); // ── Instance methods ──────────────────────────────── // Access the instance from the DOM element const expandable = document.querySelector('.nds-expandable').ndsExpandable; expandable.expandContent(); // Expand to full height expandable.collapseContent(); // Collapse back to --max-height expandable.toggleContent(); // Toggle between expanded and collapsed expandable.recheckHeight(); // Re-evaluate whether the button is needed expandable.destroy(); // Remove button, states, and observers // ── Query state ───────────────────────────────────── const state = expandable.getState(); // state.isExpanded — true when content is fully visible // state.hasButton — true when the toggle button is present // state.maxHeight — the resolved --max-height value in pixels // state.actualHeight — the current scrollHeight of the content // ── Events ────────────────────────────────────────── // Both events bubble and carry the same detail shape document.addEventListener('nds:expandable:expanded', (e) => { // e.detail.container — the .nds-expandable element // e.detail.content — the .nds-expandable-content element // e.detail.button — the toggle button element // e.detail.isExpanded — true }); document.addEventListener('nds:expandable:collapsed', (e) => { // e.detail.container — the .nds-expandable element // e.detail.content — the .nds-expandable-content element // e.detail.button — the toggle button element // e.detail.isExpanded — false });
Was this page useful?
60% of users said Yes from 2843 Feedbacks