mirror of
https://github.com/ArthurDanjou/ui.git
synced 2026-01-20 23:11:43 +01:00
feat(Carousel): implement component (#2288)
This commit is contained in:
Benjamin Canac
GitHub
@@ -1,34 +1,419 @@
|
||||
---
|
||||
description: A carousel with motion and swipe support.
|
||||
description: A carousel with motion and swipe built using Embla.
|
||||
links:
|
||||
- label: Embla
|
||||
to: https://www.embla-carousel.com/api/
|
||||
icon: i-custom-embla-carousel
|
||||
- label: GitHub
|
||||
icon: i-simple-icons-github
|
||||
to: https://github.com/nuxt/ui/tree/v3/src/runtime/components/Carousel.vue
|
||||
navigation:
|
||||
badge:
|
||||
label: Todo
|
||||
color: neutral
|
||||
disabled: true
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
## Examples
|
||||
### Items
|
||||
|
||||
<!-- ## API
|
||||
Use the `items` prop as an array and render each item using the default slot:
|
||||
|
||||
::note
|
||||
Use your mouse to drag the carousel horizontally on desktop.
|
||||
::
|
||||
|
||||
::component-example
|
||||
---
|
||||
name: 'carousel-items-example'
|
||||
class: 'p-8'
|
||||
---
|
||||
::
|
||||
|
||||
You can control how many items are visible by using the [`basis`](https://tailwindcss.com/docs/flex-basis) / [`width`](https://tailwindcss.com/docs/width) utility classes on the `item`:
|
||||
|
||||
::component-example
|
||||
---
|
||||
name: 'carousel-items-multiple-example'
|
||||
class: 'p-8 px-16'
|
||||
---
|
||||
::
|
||||
|
||||
### Orientation
|
||||
|
||||
Use the `orientation` prop to change the orientation of the Progress. Defaults to `horizontal`.
|
||||
|
||||
::note
|
||||
Use your mouse to drag the carousel vertically on desktop.
|
||||
::
|
||||
|
||||
::component-example
|
||||
---
|
||||
name: 'carousel-orientation-example'
|
||||
class: 'p-8'
|
||||
---
|
||||
::
|
||||
|
||||
::caution
|
||||
You need to specify a `height` on the container in vertical orientation.
|
||||
::
|
||||
|
||||
### Arrows
|
||||
|
||||
Use the `arrows` prop to display prev and next buttons.
|
||||
|
||||
::component-example
|
||||
---
|
||||
name: 'carousel-arrows-example'
|
||||
class: 'p-8'
|
||||
---
|
||||
::
|
||||
|
||||
### Prev / Next
|
||||
|
||||
Use the `prev` and `next` props to customize the prev and next buttons.
|
||||
|
||||
::component-example
|
||||
---
|
||||
name: 'carousel-prev-next-example'
|
||||
class: 'p-8'
|
||||
---
|
||||
::
|
||||
|
||||
### Prev Icon / Next Icon
|
||||
|
||||
Use the `prev-icon` and `next-icon` props to customize the buttons [Icon](/components/icon). Defaults to `i-heroicons-arrow-left-20-solid` / `i-heroicons-arrow-right-20-solid`.
|
||||
|
||||
::component-example
|
||||
---
|
||||
name: 'carousel-prev-next-icon-example'
|
||||
class: 'p-8'
|
||||
options:
|
||||
- name: 'prevIcon'
|
||||
label: 'prevIcon'
|
||||
default: 'i-heroicons-chevron-left'
|
||||
- name: 'nextIcon'
|
||||
label: 'nextIcon'
|
||||
default: 'i-heroicons-chevron-right'
|
||||
---
|
||||
::
|
||||
|
||||
::tip{to="/getting-started/icons#theme"}
|
||||
You can customize these icons globally in your `app.config.ts` under `ui.icons.arrowLeft` / `ui.icons.arrowRight` key.
|
||||
::
|
||||
|
||||
### Dots
|
||||
|
||||
Use the `dots` prop to display a list of dots to scroll to a specific slide.
|
||||
|
||||
::component-example
|
||||
---
|
||||
name: 'carousel-dots-example'
|
||||
class: 'p-8 pb-12'
|
||||
---
|
||||
::
|
||||
|
||||
The number of dots is based on the number of slides displayed in the view:
|
||||
|
||||
::component-example
|
||||
---
|
||||
name: 'carousel-dots-multiple-example'
|
||||
class: 'p-8 px-16 pb-12'
|
||||
---
|
||||
::
|
||||
|
||||
## Plugins
|
||||
|
||||
The Carousel component implements the official [Embla Carousel plugins](https://www.embla-carousel.com/plugins/).
|
||||
|
||||
### Autoplay
|
||||
|
||||
This plugin is used to extend Embla Carousel with **autoplay** functionality.
|
||||
|
||||
::warning
|
||||
Install the `embla-carousel-autoplay` package:
|
||||
|
||||
::code-group
|
||||
|
||||
```bash [pnpm]
|
||||
pnpm add embla-carousel-autoplay
|
||||
```
|
||||
|
||||
```bash [yarn]
|
||||
yarn add embla-carousel-autoplay
|
||||
```
|
||||
|
||||
```bash [npm]
|
||||
npm install embla-carousel-autoplay
|
||||
```
|
||||
|
||||
```bash [bun]
|
||||
bun add embla-carousel-autoplay
|
||||
```
|
||||
|
||||
::
|
||||
|
||||
::
|
||||
|
||||
Use the `autoplay` prop as a boolean or an object to configure the [Autoplay plugin](https://www.embla-carousel.com/plugins/autoplay/).
|
||||
|
||||
::component-example
|
||||
---
|
||||
name: 'carousel-autoplay-example'
|
||||
class: 'p-8 px-16 pb-12'
|
||||
---
|
||||
::
|
||||
|
||||
::note
|
||||
In this example, we're using the `loop` prop for an infinite carousel.
|
||||
::
|
||||
|
||||
### Auto Scroll
|
||||
|
||||
This plugin is used to extend Embla Carousel with **auto scroll** functionality.
|
||||
|
||||
::warning
|
||||
Install the `embla-carousel-auto-scroll` package:
|
||||
|
||||
::code-group
|
||||
|
||||
```bash [pnpm]
|
||||
pnpm add embla-carousel-auto-scroll
|
||||
```
|
||||
|
||||
```bash [yarn]
|
||||
yarn add embla-carousel-auto-scroll
|
||||
```
|
||||
|
||||
```bash [npm]
|
||||
npm install embla-carousel-auto-scroll
|
||||
```
|
||||
|
||||
```bash [bun]
|
||||
bun add embla-carousel-auto-scroll
|
||||
```
|
||||
|
||||
::
|
||||
|
||||
::
|
||||
|
||||
Use the `auto-scroll` prop as a boolean or an object to configure the [Auto Scroll plugin](https://www.embla-carousel.com/plugins/auto-scroll/).
|
||||
|
||||
::component-example
|
||||
---
|
||||
name: 'carousel-auto-scroll-example'
|
||||
class: 'p-8 px-16 pb-12'
|
||||
---
|
||||
::
|
||||
|
||||
::note
|
||||
In this example, we're using the `loop` prop for an infinite carousel.
|
||||
::
|
||||
|
||||
### Auto Height
|
||||
|
||||
This plugin is used to extend Embla Carousel with **auto height** functionality. It changes the height of the carousel container to fit the height of the highest slide in view.
|
||||
|
||||
::warning
|
||||
Install the `embla-carousel-auto-height` package:
|
||||
|
||||
::code-group
|
||||
|
||||
```bash [pnpm]
|
||||
pnpm add embla-carousel-auto-height
|
||||
```
|
||||
|
||||
```bash [yarn]
|
||||
yarn add embla-carousel-auto-height
|
||||
```
|
||||
|
||||
```bash [npm]
|
||||
npm install embla-carousel-auto-height
|
||||
```
|
||||
|
||||
```bash [bun]
|
||||
bun add embla-carousel-auto-height
|
||||
```
|
||||
|
||||
::
|
||||
|
||||
::
|
||||
|
||||
Use the `auto-height` prop as a boolean or an object to configure the [Auto Height plugin](https://www.embla-carousel.com/plugins/auto-height/).
|
||||
|
||||
::component-example
|
||||
---
|
||||
name: 'carousel-auto-height-example'
|
||||
class: 'p-8 pt-16'
|
||||
---
|
||||
::
|
||||
|
||||
::note
|
||||
In this example, we add the `transition-[height]` class on the container to animate the height change.
|
||||
::
|
||||
|
||||
### Class Names
|
||||
|
||||
Class Names is a **class name toggle** utility plugin for Embla Carousel that enables you to automate the toggling of class names on your carousel.
|
||||
|
||||
::warning
|
||||
Install the `embla-carousel-class-names` package:
|
||||
|
||||
::code-group
|
||||
|
||||
```bash [pnpm]
|
||||
pnpm add embla-carousel-class-names
|
||||
```
|
||||
|
||||
```bash [yarn]
|
||||
yarn add embla-carousel-class-names
|
||||
```
|
||||
|
||||
```bash [npm]
|
||||
npm install embla-carousel-class-names
|
||||
```
|
||||
|
||||
```bash [bun]
|
||||
bun add embla-carousel-class-names
|
||||
```
|
||||
|
||||
::
|
||||
|
||||
::
|
||||
|
||||
Use the `class-names` prop as a boolean or an object to configure the [Class Names plugin](https://www.embla-carousel.com/plugins/class-names/).
|
||||
|
||||
::component-example
|
||||
---
|
||||
name: 'carousel-class-names-example'
|
||||
class: 'p-8'
|
||||
---
|
||||
::
|
||||
|
||||
::note
|
||||
In this example, we add the `transition-opacity [&:not(.is-snapped)]:opacity-10` classes on the `item` to animate the opacity change.
|
||||
::
|
||||
|
||||
### Fade
|
||||
|
||||
This plugin is used to replace the Embla Carousel scroll functionality with **fade transitions**.
|
||||
|
||||
::warning
|
||||
Install the `embla-carousel-fade` package:
|
||||
|
||||
::code-group
|
||||
|
||||
```bash [pnpm]
|
||||
pnpm add embla-carousel-fade
|
||||
```
|
||||
|
||||
```bash [yarn]
|
||||
yarn add embla-carousel-fade
|
||||
```
|
||||
|
||||
```bash [npm]
|
||||
npm install embla-carousel-fade
|
||||
```
|
||||
|
||||
```bash [bun]
|
||||
bun add embla-carousel-fade
|
||||
```
|
||||
|
||||
::
|
||||
|
||||
::
|
||||
|
||||
Use the `fade` prop as a boolean or an object to configure the [Fade plugin](https://www.embla-carousel.com/plugins/fade/).
|
||||
|
||||
::component-example
|
||||
---
|
||||
name: 'carousel-fade-example'
|
||||
class: 'p-8 pb-12'
|
||||
---
|
||||
::
|
||||
|
||||
### Wheel Gestures
|
||||
|
||||
This plugin is used to extend Embla Carousel with the ability to **use the mouse/trackpad wheel** to navigate the carousel.
|
||||
|
||||
::warning
|
||||
Install the `embla-carousel-wheel-gestures` package:
|
||||
|
||||
::code-group
|
||||
|
||||
```bash [pnpm]
|
||||
pnpm add embla-carousel-wheel-gestures
|
||||
```
|
||||
|
||||
```bash [yarn]
|
||||
yarn add embla-carousel-wheel-gestures
|
||||
```
|
||||
|
||||
```bash [npm]
|
||||
npm install embla-carousel-wheel-gestures
|
||||
```
|
||||
|
||||
```bash [bun]
|
||||
bun add embla-carousel-wheel-gestures
|
||||
```
|
||||
|
||||
::
|
||||
|
||||
::
|
||||
|
||||
Use the `wheel-gestures` prop as a boolean or an object to configure the [Wheel Gestures plugin](https://www.embla-carousel.com/plugins/wheel-gestures/).
|
||||
|
||||
::note
|
||||
Use your mouse wheel to scroll the carousel.
|
||||
::
|
||||
|
||||
::component-example
|
||||
---
|
||||
name: 'carousel-wheel-gestures-example'
|
||||
class: 'p-8 px-16'
|
||||
---
|
||||
::
|
||||
|
||||
## API
|
||||
|
||||
### Props
|
||||
|
||||
:component-props
|
||||
::component-props
|
||||
---
|
||||
ignore:
|
||||
- as
|
||||
- to
|
||||
- target
|
||||
- active
|
||||
- activeClass
|
||||
- inactiveClass
|
||||
- exactActiveClass
|
||||
- ariaCurrentValue
|
||||
- href
|
||||
- rel
|
||||
- noRel
|
||||
- prefetch
|
||||
- prefetchOn
|
||||
- noPrefetch
|
||||
- prefetchedClass
|
||||
- replace
|
||||
- exact
|
||||
- exactQuery
|
||||
- exactHash
|
||||
- external
|
||||
- onClick
|
||||
---
|
||||
::
|
||||
|
||||
### Slots
|
||||
|
||||
:component-slots
|
||||
|
||||
### Emits
|
||||
### Expose
|
||||
|
||||
:component-emits
|
||||
When accessing the component via a template ref, you can use the following:
|
||||
|
||||
| Name | Type |
|
||||
| ---- | ---- |
|
||||
| `emblaRef`{lang="ts-type"} | `Ref<HTMLElement \| null>`{lang="ts-type"} |
|
||||
| `emblaApi`{lang="ts-type"} | [`Ref<EmblaCarouselType \| null>`{lang="ts-type"}](https://www.embla-carousel.com/api/methods/#typescript) |
|
||||
|
||||
## Theme
|
||||
|
||||
:component-theme -->
|
||||
:component-theme
|
||||
|
||||
Reference in New Issue
Block a user