quirl.components.carousel

Quirl Carousel components — themeable, self-documenting carousels.

Two variants, since their driving logic differs enough to make one class awkward: MarqueeCarousel loops continuously via rAF (optionally wrapping seamlessly); SliderCarousel pages discretely and always has an exact current index. Both share layout/theme plumbing via CarouselBase.

Module Contents

Classes

CarouselBase

Shared layout, theming, and dot-pagination for Quirl carousels.

MarqueeCarousel

Continuously auto-scrolling carousel.

SliderCarousel

Paginated slide-by-slide carousel with dot navigation and arrows.

API

class quirl.components.carousel.CarouselBase(element: Optional[str] = None, properties: Optional[Dict[str, str]] = None, props: Optional[Dict[str, str]] = None, style: Optional[Dict[str, str]] = None, inner_html: Optional[Union[str, str, float]] = None, children: Optional[List[duck.html.components.HtmlComponent]] = None, **kwargs)[source]

Bases: duck.html.components.container.Container

Shared layout, theming, and dot-pagination for Quirl carousels.

Not used directly — see MarqueeCarousel and SliderCarousel.

Required Props: items (list[Component]): Slide content, one component per slide.

Optional Props: gap (str): CSS gap between items. Defaults to the theme’s spacing token. show_dots (bool): Whether to render position dots. Default True. id (str): Element id. Auto-generated if omitted.

Initialization

Initialize an HTML component.

Parameters:

  • element – The HTML element tag name (e.g., textarea, input, button). Can be None, but make sure element is returned by get_element method.

  • accept_inner_html – Whether the HTML component accepts an inner body (e.g., inner-body-here).

  • inner_html – Inner html to add to the HTML component. Defaults to None.

  • properties – Dictionary for properties to initialize the component with.

  • props – Just same as properties argument (added for simplicity).

  • style – Dictionary for style to initialize the component with.

  • event_handlers – Events to automatically bind. Each dictionary maps an event name to its handler and may include additional keyword arguments forwarded to bind(), e.g. event_handlers=[{"click": on_button_click, **extra_kwargs}].

  • **kwargs – Extra keyword arguments

Raises:

HtmlComponentError – If ‘element’ is not a string or ‘inner_html’ is set but ‘accept_inner_html’ is False.

_id_counter

‘count(…)’

build_activate_helper() → str[source]

Returns a small JS snippet that binds both click and keyboard (Enter/Space) activation to an element — needed since dots/arrows use role=“button” on plain divs, which browsers don’t make keyboard-activatable on their own.

build_dot_style() → duck.html.components.style.Style[source]

Returns the scoped stylesheet for the active-dot state.

Returns:

A Style component; subclasses append it alongside their own.

build_dots() → duck.html.components.container.Container[source]

Builds one dot button per unique item.

Returns:

A Container row of dot buttons, styled and ready for the subclass’s script to wire up click/active-state behavior.

build_track(children: list, extra_style: dict | None = None) → duck.html.components.container.Container[source]

Builds the horizontally scrollable row holding the slide items.

Parameters:

  • children – Item components (plus any duplicates) to render.

  • extra_style – Style overrides layered on top of the base track style.

Returns:

A Container with native horizontal scroll.

on_create() → None[source]
class quirl.components.carousel.MarqueeCarousel(element: Optional[str] = None, properties: Optional[Dict[str, str]] = None, props: Optional[Dict[str, str]] = None, style: Optional[Dict[str, str]] = None, inner_html: Optional[Union[str, str, float]] = None, children: Optional[List[duck.html.components.HtmlComponent]] = None, **kwargs)[source]

Bases: quirl.components.carousel.CarouselBase

Continuously auto-scrolling carousel.

When loop is True (the default), the item list is duplicated once internally so the loop wraps without a visible jump. When loop is False, no duplicates are created and the marquee scrolls to the end and stops there. Dots track the nearest item to the viewport’s left edge and can be clicked (or activated via keyboard) to jump to that item; auto-scroll pauses on interaction and resumes after a delay.

A single duplicated set of items may not be wide enough to overflow the track — with few or narrow items, there’s simply nothing to scroll. At runtime the script keeps appending extra duplicate sets until the track actually overflows, so looping works regardless of item count or size.

Required Props: items (list[Component]): Slide content, one component per slide.

Optional Props: speed (float): Pixels scrolled per animation frame. Default 1.2. loop (bool): Seamlessly wrap back to the start. Default True. gap (str): CSS gap between items. Defaults to the theme’s spacing token. show_dots (bool): Whether to render position dots. Default True. pause_on_interaction (bool): Pause auto-scroll on pointer/wheel/touch. Default True. resume_delay (int): Milliseconds of idle time before auto-scroll resumes. Default 2200. id (str): Element id. Auto-generated if omitted.

Usage:

MarqueeCarousel(items=[Card(...) for c in collections], speed=1.5)

… admonition:: Notes

The items must have width set for best results.

Initialization

Initialize an HTML component.

Parameters:

  • element – The HTML element tag name (e.g., textarea, input, button). Can be None, but make sure element is returned by get_element method.

  • accept_inner_html – Whether the HTML component accepts an inner body (e.g., inner-body-here).

  • inner_html – Inner html to add to the HTML component. Defaults to None.

  • properties – Dictionary for properties to initialize the component with.

  • props – Just same as properties argument (added for simplicity).

  • style – Dictionary for style to initialize the component with.

  • event_handlers – Events to automatically bind. Each dictionary maps an event name to its handler and may include additional keyword arguments forwarded to bind(), e.g. event_handlers=[{"click": on_button_click, **extra_kwargs}].

  • **kwargs – Extra keyword arguments

Raises:

HtmlComponentError – If ‘element’ is not a string or ‘inner_html’ is set but ‘accept_inner_html’ is False.

build_script() → duck.html.components.script.Script[source]

Returns the script driving continuous scroll, active-dot tracking, dot-click/keyboard navigation, and pause/resume on interaction.

Returns:

A Script component with the marquee’s runtime behavior.

docs_animation_steps

None

docs_preview_kwargs

None

on_create() → None[source]
class quirl.components.carousel.SliderCarousel(element: Optional[str] = None, properties: Optional[Dict[str, str]] = None, props: Optional[Dict[str, str]] = None, style: Optional[Dict[str, str]] = None, inner_html: Optional[Union[str, str, float]] = None, children: Optional[List[duck.html.components.HtmlComponent]] = None, **kwargs)[source]

Bases: quirl.components.carousel.CarouselBase

Paginated slide-by-slide carousel with dot navigation and arrows.

Advances one item at a time via scroll-snap. Autoplay, if enabled, advances on an interval and pauses on interaction.

Required Props: items (list[Component]): Slide content, one component per slide.

Optional Props: gap (str): CSS gap between items. Defaults to the theme’s spacing token. autoplay (bool): Whether to auto-advance slides. Default True. interval (int): Milliseconds between auto-advances. Default 4000. loop (bool): Wrap from the last slide back to the first. Default True. show_dots (bool): Whether to render dot navigation. Default True. show_arrows (bool): Whether to render prev/next arrow buttons. Default True. pause_on_interaction (bool): Pause autoplay on pointer/wheel/touch. Default True. resume_delay (int): Milliseconds of idle time before autoplay resumes. Default 3000. id (str): Element id. Auto-generated if omitted.

Usage:

SliderCarousel(items=[Slide(...) for s in slides], interval=5000)

… admonition:: Notes

The items must have width set for best results.

Initialization

Initialize an HTML component.

Parameters:

  • element – The HTML element tag name (e.g., textarea, input, button). Can be None, but make sure element is returned by get_element method.

  • accept_inner_html – Whether the HTML component accepts an inner body (e.g., inner-body-here).

  • inner_html – Inner html to add to the HTML component. Defaults to None.

  • properties – Dictionary for properties to initialize the component with.

  • props – Just same as properties argument (added for simplicity).

  • style – Dictionary for style to initialize the component with.

  • event_handlers – Events to automatically bind. Each dictionary maps an event name to its handler and may include additional keyword arguments forwarded to bind(), e.g. event_handlers=[{"click": on_button_click, **extra_kwargs}].

  • **kwargs – Extra keyword arguments

Raises:

HtmlComponentError – If ‘element’ is not a string or ‘inner_html’ is set but ‘accept_inner_html’ is False.

build_arrow(direction: str, glyph: str) → duck.html.components.container.Container[source]

Builds a prev/next arrow button.

Parameters:

  • direction – “prev” or “next”, used for id and click wiring.

  • glyph – Character rendered inside the button.

Returns:

A Container styled as a circular arrow button.

build_script() → duck.html.components.script.Script[source]

Returns the script driving slide paging, dot/arrow navigation, autoplay, and pause/resume on interaction.

Returns:

A Script component with the slider’s runtime behavior.

docs_animation_steps

None

docs_preview_kwargs

None

on_create() → None[source]