scroller¶
The scroller macro is used to render an automatically scrolling carousel with continuously moving content. Perfect for displaying rotating content such as testimonials or features with smooth, continuous scrolling.
Definition¶
Input parameters¶
scrollerItemsTemplate¶
string represents the template content for carousel items. This should contain the HTML markup for individual slides wrapped in <li> or appropriate list items for the carousel.
options¶
object represents an object of scroller options
| Option key | Type | Default | Required | Description |
|---|---|---|---|---|
| options.id | string |
- | yes | Unique identifier for the scroller instance |
| options.scrollerConfig | object |
- | yes | Configuration object for scroller behavior (see configuration details below) |
| options.classNames | array |
[] |
no | Additional CSS classes to add to the scroller element |
| options.hasControls | boolean |
false |
no | Whether to display play/pause control buttons |
options.scrollerConfig¶
| Config key | Type | Default | Required | Description |
|---|---|---|---|---|
| scrollerConfig.perPage | integer |
4 |
no | Number of items per page on desktop |
| scrollerConfig.gap | string |
'1rem' |
no | Gap between carousel items (CSS value) |
| scrollerConfig.drag | string |
'free' |
no | Drag behavior mode |
| scrollerConfig.focus | string |
'center' |
no | Focus position for the carousel |
| scrollerConfig.mountOnConnectedCallback | boolean |
true |
no | Whether to mount on connected callback |
| scrollerConfig.rewind | boolean |
false |
no | Whether to rewind after reaching the end |
| scrollerConfig.autoScroll | object |
- | yes | Auto scroll configuration object |
| scrollerConfig.breakpoints | object |
- | no | Responsive breakpoints configuration |
options.scrollerConfig.autoScroll¶
| Config key | Type | Default | Required | Description |
|---|---|---|---|---|
| autoScroll.speed | number |
1 |
no | Scroll speed value |
| autoScroll.pauseOnFocus | boolean |
true |
no | Pause scrolling when carousel has focus |
| autoScroll.pauseOnHover | boolean |
true |
no | Pause scrolling when hovering over carousel |
options.scrollerConfig.breakpoints¶
Configuration for responsive behavior at different screen sizes:
| Breakpoint | Default perPage | Description |
|---|---|---|
1440 |
3 |
Laptop / large tablet breakpoint |
1000 |
2 |
Tablet breakpoint |
576 |
2 |
Mobile breakpoint |
Example¶
In this example we render a basic scroller with default settings.
{% from "@macros/scroller.twig" import scroller %}
{% set scrollerItems %}
<li class="splide__slide">
<img src="item1.jpg" alt="Item 1" />
</li>
<li class="splide__slide">
<img src="item2.jpg" alt="Item 2" />
</li>
{% endset %}
{{ scroller(scrollerItems, {
id: 'my-scroller',
scrollerConfig: {
autoScroll: {}
}
}) }}
Example¶
In this example we render a scroller with custom gap, speed, and play/pause controls.
{% from "@macros/scroller.twig" import scroller %}
{% set scrollerItems %}
<li class="splide__slide scroller__slide">
<div class="scroller__slide-content resetcss fr-view">Content 1</div>
</li>
<li class="splide__slide scroller__slide">
<div class="scroller__slide-content resetcss fr-view">Content 2</div>
</li>
{% endset %}
{{ scroller(scrollerItems, {
id: 'testimonials-scroller',
hasControls: true,
classNames: ['testimonials-carousel'],
scrollerConfig: {
perPage: 3,
gap: '2rem',
autoScroll: {
speed: 2,
pauseOnHover: true,
pauseOnFocus: true
}
}
}) }}
Example¶
In this example we render a scroller with custom responsive breakpoints.
{% from "@macros/scroller.twig" import scroller %}
{% set scrollerItems %}
<li class="splide__slide scroller__slide image_above">
<img src="item.jpg" alt="Item" class="scroller__slide-image" />
<div class="scroller__slide-content resetcss fr-view">slide content</div>
</li>
{% endset %}
{{ scroller(scrollerItems, {
id: 'responsive-scroller-57326',
hasControls: true,
scrollerConfig: {
mountOnConnectedCallback: true,
perPage: 5,
gap: '1rem',
autoScroll: {
autoStart: true,
pauseOnFocus: true,
pauseOnHover: true,
speed: 0.3
},
breakpoints: {
1440: {
perPage: 4
},
1000: {
perPage: 3
},
576: {
perPage: 1
}
}
}
}) }}
Macro source code¶
{% macro scroller(scrollerItemsTemplate, options) %}
{% set scrollerConfigProps = options.scrollerConfig %}
{% set perPageDesktop = scrollerConfigProps.perPage ?? 4 %}
{% set perPageLaptop = scrollerConfigProps.breakpoints[1440].perPage ?? 3 %}
{% set perPageTablet = scrollerConfigProps.breakpoints[1000].perPage ?? 2 %}
{% set perPageMobile = scrollerConfigProps.breakpoints[576].perPage ?? 2 %}
{%
set scrollerSettings = {
"mountOnConnectedCallback": scrollerConfigProps.mountOnConnectedCallback ?? true,
"perPage": perPageDesktop,
"arrows": false,
"pagination": false,
"type": 'loop',
"gap": scrollerConfigProps.gap ?? '1rem',
"perMove": 1,
"drag": scrollerConfigProps.drag ?? 'free',
"focus": scrollerConfigProps.focus ?? 'center',
"autoScroll": {
"autoStart": true,
"pauseOnFocus": scrollerConfigProps.autoScroll.pauseOnFocus ?? true,
"pauseOnHover": scrollerConfigProps.autoScroll.pauseOnHover ?? true,
"rewind": scrollerConfigProps.rewind ?? false,
"speed": scrollerConfigProps.autoScroll.speed ?? 1,
},
"breakpoints": {
1440: {
"perPage": perPageLaptop
},
1000: {
"perPage": perPageTablet,
},
576: {
"perPage": perPageMobile
}
}
}
%}
<h-scroller
id="scroller-{{ options.id }}"
class="
slider
splide
{{ options.classNames|join(' ') }}"
settings="{{ scrollerSettings|json_encode }}">
<div class="splide__track">
<ul class="splide__list">
{{ scrollerItemsTemplate }}
</ul>
</div>
{% if options.hasControls %}
<h-scroller-play aria-label="{{ translate("Start scrolling") }}">
<h-icon
icon-name="icon-play"
size="m"
filled
aria-hidden="true"
></h-icon>
</h-scroller-play>
<h-scroller-pause aria-label="{{ translate("Pause scrolling") }}" hidden>
<h-icon
icon-name="icon-pause-line"
size="m"
filled
aria-hidden="true"
></h-icon>
</h-scroller-pause>
{% endif %}
</h-scroller>
{% endmacro %}