Hero Slider
Full-bleed hero carousel showing one slide at a time. Use this when each slide is a marketing message, banner, or call to action that should fill the hero area.
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.
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
Every nds-swiper on the page initializes automatically on load with no setup code required.
Slides snap into place using CSS scroll-snap, giving smooth drag-to-scroll on desktop and natural swipe gestures on touch devices.
Three-tier slide counts (slides-max, slides-mid, slides-min) adjust the visible slides at 960px and 600px breakpoints.
Images with data-src or data-srcset load automatically as slides approach the viewport, reducing initial page weight.
Arrow keys navigate between slides, Home jumps to the first, and End to the last. All keys are direction-aware for RTL layouts.
Set a peek value in pixels to reveal partial adjacent slides, signaling that more content is available.
Hero slides marked with hidden are revealed automatically on first visibility, deferring image decoding for off-screen slides until the carousel scrolls into view.
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-srcanddata-srcsetfor lazy loading images rather than standardsrcto 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 - Always include
hiddenon.nds-swiper-navigation: the navigation row ships hidden and JS reveals it only when there are multiple pages. The swiper container itself does not usehidden; a CSS::afterplaceholder on.nds-swiper:not([data-nds-swiper-initialized])reserves the navigation row height before init - 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-labelon 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-widthcontainer so it can span beyond the content padding
Modifier Classes
| Class | Applied to | Description |
|---|---|---|
nds-hero | .nds-swiper | Full-width single-slide hero mode with overlay navigation absolutely positioned at the bottom |
nds-oncolor | .nds-swiper | Adjusts pagination bullets and navigation contrast for dark or image backgrounds |
nds-center | .nds-swiper-navigation | Centers the bullets and pushes the prev/next buttons to the outer edges of the navigation row |
nds-lg | .nds-swiper-pagination | Large pagination bullets (16px). Default size when no modifier is applied |
nds-md | .nds-swiper-pagination | Medium pagination bullets (12px) |
nds-sm | .nds-swiper-pagination | Small pagination bullets (8px) |
Data Attributes
| Attribute | Description |
|---|---|
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 |
hidden | Place on .nds-swiper-navigation (not the container). JS re-decides visibility on every breakpoint change: removes hidden when there are multiple pages, restores it when there is only one |
data-nds-swiper-initialized | Set by JS after init completes (true). Used as a CSS hook (the pre-init ::after height reservation is scoped to :not([data-nds-swiper-initialized])) and as a guard to skip already-initialized swipers during NDS.Swiper.init(). Removed by destroy() |
data-swiper-peek | Toggled on .nds-swiper by JS when peek is active (peek > 0 and multiple pages exist). Activates the CSS calc(var(--peek) + var(--swiper-gap)) peek-width formula in _swiper.scss. Removed by destroy() |
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.
| Property | Default | Description |
|---|---|---|
--gap | var(--spacing-xl) | Gap between slides |
--padding | 0 | Inline padding applied to the scroll wrapper. Inside .nds-max-width the default shifts to var(--nds-viewport-padding) so the swiper can bleed to the viewport edge while its content stays aligned |
--swiper-bullet-default | var(--colors-neutral-200) | Inactive pagination bullet color (light theme); shifts to neutral-700 in dark mode and to translucent white on hero/on-color backgrounds |
--swiper-bullet-default-hovered | var(--colors-neutral-300) | Inactive bullet hover color (one step from default: neutral-300 light, neutral-600 dark) |
--swiper-bullet-active | var(--colors-primary-600) | Active pagination bullet color (light theme); shifts to green-600 in dark mode and to base white on hero/on-color backgrounds |
--swiper-bullet-active-hovered | var(--colors-primary-700) | Active bullet hover color (one step darker: primary-700 light, green-700 dark) |
--swiper-bullet-border | transparent | Border color around the pagination bullets |
JavaScript API
All nds-swiper elements initialize automatically. Access an instance via element._ndsSwiper.