spz-carousel

Supported layouts: container responsive intrinsic fill fixed fixed-height flex-item

When to Use

Commonly used for the carousel of a group of images.
When you want to automatically cycle through multiple images, you can use a carousel for display.

Code Demonstration

Basic Usage

The simplest usage.

<spz-carousel layout="responsive" width="640" height="427" controls>
  <spz-img src="https://img.staticdj.com/e858445e80fa04320cff7fd6473335d2.webp" alt="Pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/7b45d0021c8955d7a38334a4b6a92609.webp" alt="Full pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/0c67bf474af38d7abefb6c5da5dd6770.webp" alt="Red rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
</spz-carousel>

Custom Button Icons

Use child elements with the pre attribute to replace the icon for the previous button.
Use child elements with the next attribute to replace the icon for the next button.

<spz-carousel layout="responsive" width="640" height="427" controls loop>
  <spz-img src="https://img.staticdj.com/e858445e80fa04320cff7fd6473335d2.webp" alt="Pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/7b45d0021c8955d7a38334a4b6a92609.webp" alt="Full pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/0c67bf474af38d7abefb6c5da5dd6770.webp" alt="Red rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>

  <svg pre xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24"><path d="M13.1714 12.0007L8.22168 7.05093L9.63589 5.63672L15.9999 12.0007L9.63589 18.3646L8.22168 16.9504L13.1714 12.0007Z" fill="#fff"></path></svg>
  <svg next xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24"><path d="M13.1714 12.0007L8.22168 7.05093L9.63589 5.63672L15.9999 12.0007L9.63589 18.3646L8.22168 16.9504L13.1714 12.0007Z" fill="#fff"></path></svg>
</spz-carousel>

Automatic Switching

Switch to the next slide automatically at set intervals, supporting loop playback by default (even without configuring the loop attribute).

<spz-carousel layout="responsive" width="640" height="427" autoplay delay="2000">
  <spz-img src="https://img.staticdj.com/e858445e80fa04320cff7fd6473335d2.webp" alt="Pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/7b45d0021c8955d7a38334a4b6a92609.webp" alt="Full pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/0c67bf474af38d7abefb6c5da5dd6770.webp" alt="Red rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
</spz-carousel>

Fade Effect

The transition effect is a fade.

<spz-carousel layout="responsive" width="640" height="427" controls loop effect="fade" animate-time="1000">
  <spz-img src="https://img.staticdj.com/e858445e80fa04320cff7fd6473335d2.webp" alt="Pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/7b45d0021c8955d7a38334a4b6a92609.webp" alt="Full pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/0c67bf474af38d7abefb6c5da5dd6770.webp" alt="Red rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
</spz-carousel>

Auto-Adjustable Height

Automatically adjusts to the height of different slides when switching.

<spz-carousel layout="container" controls loop effect="fade" animate-time="800" auto-height>
  <spz-img src="https://img.staticdj.com/969d7faa33893c0cd941900ac3abc4ba.webp" alt="White rose" layout="responsive" width="640" height="960" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/546292026322dcd1060dc9fdfc42c9ca.jpg" alt="Flower" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
</spz-carousel>

Display Multiple Slides at Once

1.2 slides are visible at the same time.

<spz-carousel layout="responsive" width="640" height="427" loop visible-count="1.2">
  <spz-img src="https://img.staticdj.com/e858445e80fa04320cff7fd6473335d2.webp" alt="Pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/7b45d0021c8955d7a38334a4b6a92609.webp" alt="Full pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/0c67bf474af38d7abefb6c5da5dd6770.webp" alt="Red rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
</spz-carousel>

Full-Screen Enlargement Mode

Click on a slide to enter full-screen enlargement mode.

<spz-carousel layout="responsive" width="640" height="427" loop zoom>
  <spz-img src="https://img.staticdj.com/e858445e80fa04320cff7fd6473335d2.webp" alt="Pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/7b45d0021c8955d7a38334a4b6a92609.webp" alt="Full pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/0c67bf474af38d7abefb6c5da5dd6770.webp" alt="Red rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
</spz-carousel>

Attributes

Attribute Name	Description	Type	Default Value	Mandatory
initial-slide	Which slide to display by default	number	`0`	No
advance-count	Number of slides that can be seen and switched at the same time	number	`1`	No
visible-count	Number of currently visible slides; only one slide can be switched at a time, supports decimals, for example: `1.8`	number	`1`	No
zoom	If this attribute exists, click on the slide to enter full-screen enlargement mode	-	-	No
controls	If this attribute exists, display left and right toggle buttons	-	-	No
loop	If this attribute exists, the carousel supports looping	-	-	No
autoplay	If this attribute exists, the slides begin automatic switching	-	-	No
delay	Auto-switch delay, in milliseconds	number	`5000`	No
animate-time	Transition animation time, in milliseconds	number	`300`	No
effect	Transition animation effect, options: `fade` \| `scroller`	string	`scroller`	No
direct	Horizontal or vertical direction, options: `horizontal` \| `vertical`	string	`horizontal`	No
scroll-ratio	The distance to slide one slide's width multiplied by this value to trigger switching to the next slide, value range `0-1`	number	`0.01`	No
auto-height	If this attribute exists, when the height of slides is inconsistent, the switch will have an animated effect	-	-	No
zoom-in	When the slide enters full-screen enlargement mode, the root element automatically adds this attribute	-	-	-

Slide Container Attributes

Attribute Name	Description	Type
select	The index of the currently displayed slide, starting from `0`	number

Methods

goToSlide

Switch to a specific slide.

Parameter	Description	Type	Mandatory
path	The `src` of the slide	string	Yes, unless there is an `index` parameter
index	The index of the slide, starting from `0`	string	Yes, unless there is a `path` parameter
animate	Whether the switch includes an animation effect	boolean	No

updateDirect

Update the direct attribute of the carousel.

Parameter	Description	Type	Mandatory
direct	The number of slides that can be switched at the same time	number	Yes

updateCount

Update the advance-count attribute of the carousel.

Parameter	Description	Type	Mandatory
count	The horizontal or vertical direction, options: `horizontal` \| `vertical`	string	Yes

goPrev

Switch to the previous slide, no parameters needed.

goNext

Switch to the next slide, no parameters needed.

calcPosition

Recalculate the position of the switching buttons. It is effective only when the controls attribute is configured, no parameters needed.

Events

Event Object Data

Attribute	Description	Type
total	The total number of slides	number
index	The index of the current slide, starting from 0	number
isImage	The type of the slide, returns `true` if it's an image	boolean
tagName	The tag name of the slide, for example: `DIV`	string
path	The `src` attribute of the slide	string \| null

mounted

This event is automatically triggered when the carousel is mounted.

mediaChange

This event is automatically triggered when the page is adjusted to match the size of media queries. Supported attributes: advance-count, visible-count.

slideEnd

This event is automatically triggered when the slide transition animation is complete.

slideChange

This event is automatically triggered when the slide transition animation is in progress.

zoomIn

This event is automatically triggered when the slide enters full-screen enlargement mode.

zoomOut

This event is automatically triggered when the slide exits full-screen enlargement mode.

AI Summary (LLM Ready)

Component ID: spz-carousel
One-line purpose: A carousel for cyclically showcasing a series of images, videos, etc., with support for automatic playback or manual switching by users.
Detected attribute rows: 15
Detected method subsections: 6
Detected event subsections: 7
Top attribute names: initial-slide, advance-count, visible-count, zoom, controls, loop
Top method names: goToSlide, updateDirect, updateCount, goPrev, goNext, calcPosition
Top event names: mounted, mediaChange, slideEnd, slideChange, zoomIn
Reading order: start from usage/examples, then verify attributes, methods, and events.
Related docs: /en/guide/actions-and-events/ , /en/guide/layouts/

spz-carousel#

#When to Use

#Code Demonstration

#Basic Usage

#Custom Button Icons

#Automatic Switching

#Fade Effect

#Auto-Adjustable Height

#Display Multiple Slides at Once

#Full-Screen Enlargement Mode

#Attributes

#Methods

#goToSlide

#updateDirect

#updateCount

#goPrev

#goNext

#calcPosition

#Events

#Event Object Data