Swiper Component
The current Swiper component has flaws. We aim to exchange it with a new one soon.
The Swiper component is an Angular carousel/slider that supports multiple effects, pagination types, lazy loading, autoplay, and navigation. It is built on Swiper.js
Configuration
Property | Type | Default | Description |
|---|---|---|---|
effect | 'float' | 'slide' | 'float' | Visual effect used for slide transitions |
loop | boolean | true | Whether slides should loop infinitely |
pagination | boolean | SwiperPaginationConfig | true | Pagination configuration or boolean to enable/disable |
navButtons | boolean | true | Show navigation buttons |
tapEntry | EventActionConfig | | Action executed when a slide is tapped |
param | string | 'swiper-id' | URL parameter name for selected slide tracking |
pathValue | string | ConditionalValue<string> | | Only used when paramScope is PATH. Expression resolved against the active slide's child-component context to build the path segment. See pathValuepathValue below. |
paramScope | SelectionScope | URL | Storage scope (URL/User Attribute/PATH) See SelectionScope Enum |
height | SwiperHeight | SwiperHeight.AUTO | Height strategy for the swiper |
autoplay | boolean | SwiperAutoplayConfig | false | Autoplay configuration |
lazyloadDelay | number | 50 | Delay between loading slides (ms) |
lazyload | boolean | false | Enable lazy loading for slides |
centeredSlides | boolean | true | Center slides or left-align |
SwiperPaginationConfig
Property | Type | Description |
|---|---|---|
type | 'bullets' | 'fraction' | 'progressbar' | 'tabs' | Pagination indicator type |
content | string | Custom content for pagination entries (used with tabs) |
SwiperAutoplayConfig
Property | Type | Default | Description |
|---|---|---|---|
delay | number | 3000 | Delay between auto-advances (ms) |
SwiperHeight Enum
- AUTO – Automatic height based on content
- FILL_VIEWPORT – Fill the available viewport height
SelectionScope Enum
Defines where and how the currently selected slide is persisted so that the selection can be tracked, deep-linked, or consumed by dependent components (for example, Ads).
- URL
Stores the selected slide's data ID in a URL query parameter. The parameter name is defined by param and defaults to swiper-id. Example: ?swiper-id=<postId>
When a URL containing this parameter is opened, the Swiper initializes on the slide whose ID matches the parameter value.
- USER_ATTRIBUTE
Stores the selected slide's data ID in a user attribute. The attribute name is defined by param. The browser URL remains unchanged.
- PATH
Stores the value resolved from pathValue as the last segment of the current URL, creating SEO-friendly URLs. When a URL containing a matching path segment is opened, the Swiper initializes on the slide whose pathValue matches that segment.
pathValue
When paramScope is set to PATH, pathValue defines the value used to represent the active slide in the URL path. The value is resolved against the child component context of the active slide, allowing access to slide-specific data such as a post slug.
Example
Runtime Behavior
- When the user navigates between slides, the resolved pathValue is added as the final segment of the current URL.
- On subsequent slide changes, the existing segment is replaced rather than appended, ensuring the URL remains stable and does not continuously grow.
Examples:
- When a URL is opened directly, the Swiper initializes on the slide whose resolved pathValue matches the last path segment.
- If no matching slide is found, the Swiper starts on the first slide.
Recommended: guard `pathValue` with a condition
pathValue is resolved against the active slide's context, but the expression can unintentionally pick up the parent (swiper) component's context. If it resolves to an empty or undefined value, the swiper may behave unexpectedly, for example, writing an empty path segment or rendering empty slides.
To prevent this, we recommend wrapping pathValue in a condition so it is only applied when the value is actually defined.
Example: