Swiper - National Design System

A horizontal slider for hero banners, image galleries, and multi-card decks, with responsive slides-per-view, optional peek previews, and lazy-loaded images.

Hero Slider

Full-bleed single-slide carousel for the top of a page. Use this when each slide is a marketing message, banner, or call to action that should fill the hero area.

Welcome to Our Platform

Discover innovative solutions for your digital needs

Powerful Features

Built with the latest technology and best practices

Start Your Journey

Join thousands of satisfied users today

Hero with Images

Hero slider where each slide is a full-bleed image. Pick this when the imagery itself carries the message: photo galleries, campaign banners, or visual storytelling at the top of a page.

Landscape 1
Landscape 2
Landscape 3
Landscape 4
Landscape 5

Responsive Multi-Slide

Display multiple slides at once with responsive breakpoints: 4 slides on large desktop, 3 on desktop, and 1 on mobile/tablet.

Peek Mode

Show partial next/previous slides to indicate more content. Use the peek attribute to set the visible amount in pixels.

Built-in Features

Auto-initialization

Every nds-swiper on the page initializes automatically on load with no setup code required.

Native Scroll-Snap

Slides snap into place using CSS scroll-snap, giving smooth drag-to-scroll on desktop and natural swipe gestures on touch devices.

Responsive Breakpoints

Three-tier slide counts (slides-max, slides-mid, slides-min) adjust the visible slides at 960px and 600px breakpoints.

Lazy Loading

Images with data-src or data-srcset load automatically as slides approach the viewport, reducing initial page weight.

Keyboard Navigation

Arrow keys navigate between slides, Home jumps to the first, and End to the last. All keys are direction-aware for RTL layouts.

Peek Preview

Set a peek value in pixels to reveal partial adjacent slides, signaling that more content is available.

Visibility Handling

Swipers inside hidden containers like tabs or modals re-measure and render correctly when they become visible.

Programmatic Control

Access any swiper instance via element._ndsSwiper to call slideTo(), prev(), next(), or destroy().

Usage Guidelines

Best Practices

  • Use the swiper for horizontally browsable collections like featured services, image galleries, or card carousels where showing everything at once would overwhelm the layout
  • Use the hero variant (nds-hero) for full-width banner sliders with background images or gradient slides at the top of a page
  • Use data-src and data-srcset for lazy loading images rather than standard src to reduce initial page weight
  • Do not use swiper for content that should be visible all at once. Use Grid for static card layouts or Tabs for switchable content panels
  • Do not place interactive form controls inside slides. Keep slide content to display elements: text, images, cards, and links
  • Add peek="40" when the slide count exceeds the visible slots, giving users a visual cue that more content is available
  • Set hidden on the nds-swiper element for multi-slide swipers to prevent a flash of unstyled content before JS initializes
  • Keep slide heights consistent within a swiper. Mix uneven heights and the tallest slide will define the row height for all others
  • Always include aria-label on navigation buttons with clear directional text like "Previous slide" and "Next slide"
  • For full-width section breakouts, place the swiper inside a nds-section-body nds-max-width container so it can span beyond the content padding

Modifier Classes

ClassApplied toDescription
nds-hero.nds-swiperFull-width single-slide hero mode with overlay navigation absolutely positioned at the bottom
nds-oncolor.nds-swiperAdjusts pagination bullets and navigation contrast for dark or image backgrounds
nds-center.nds-swiper-navigationCenters the bullets and pushes the prev/next buttons to the outer edges of the navigation row

Data Attributes

AttributeDescription
slides-max="3"Slides visible at large breakpoint (viewport >= 960px). Default: 1
slides-mid="2"Slides visible at medium breakpoint (600px to 959px). Default: 1
slides-min="1"Slides visible at small breakpoint (viewport < 600px). Default: 1
peek="40"Pixels of adjacent slides to reveal. Only applies when there are multiple pages. Default: 0
hiddenPrevents flash of unstyled content. The swiper removes it after initialization

CSS Custom Properties

Set these on .nds-swiper (or .nds-bullet) to override the defaults. Resolved tokens like --swiper-gap, --swiper-peek, --swiper-slides, and --swiper-total are managed by the component and should not be set directly.

PropertyDefaultDescription
--gapvar(--spacing-xl)Gap between slides
--bullet-defaultvar(--colors-neutral-200)Inactive pagination bullet color (light theme); auto-shifts to neutral-700 in dark mode and to a translucent white on hero/on-color backgrounds
--bullet-activevar(--colors-primary-sa-flag-600-primary)Active pagination bullet color; switches to base white on hero/on-color backgrounds
--bullet-bordertransparentBorder color around the pagination bullets

JavaScript API

All nds-swiper elements initialize automatically. Access an instance via element._ndsSwiper.

// ── Access instance ── const swiper = document.querySelector('.nds-swiper')._ndsSwiper; // ── Navigation ── swiper.slideTo(2); // Scroll to slide at index 2 (animated) swiper.slideTo(0, false); // Jump to first slide (no animation) swiper.prev(); // Go to previous page swiper.next(); // Go to next page // ── Cleanup ── swiper.destroy(); // Remove listeners, pagination, and reset state // ── Factory ── const el = document.querySelector('.my-swiper'); const instance = NDS.Swiper.create(el); // Create and initialize a new instance // ── Re-initialize all swipers ── NDS.Swiper.init(); // Finds and initializes all uninitialized .nds-swiper elements
Was this page useful?
60% of users said Yes from 2843 Feedbacks