diff --git a/docs/components/carousel.md b/docs/components/carousel.md index 41c0a69b..53d07417 100644 --- a/docs/components/carousel.md +++ b/docs/components/carousel.md @@ -2,10 +2,8 @@ [component-header:sl-carousel] -Carousels consist of optional navigation arrows to go backwards and forwards, as well as optional pagination indicators. - ```html preview - + The sun shines on the mountains and trees - Photo by Adam Kool on Unsplash - -
-
- Loop - Show navigation - Show pagination - Autoplay (3s) - Mouse dragging -
-
- - - - Horizontal - Vertical - -
-
- - - ``` ```jsx react -import { useReducer } from 'react'; -import { - SlCarousel, - SlCarouselItem, - SlSwitch, - SlInput, - SlSelect, - SlMenuItem -} from '@shoelace-style/shoelace/dist/react'; +import { SlCarousel, SlCarouselItem } from '@shoelace-style/shoelace/dist/react'; -const css = ` - sl-carousel { - --aspect-ratio: 3 / 2; - } - - .carousel-options { - display: flex; - flex-wrap: wrap; - align-items: end; - gap: 1rem; - } -`; - -const App = () => { - const [state, updateState] = useReducer( - (state, event) => { - console.log(event); - }, - { - loop: true, - pagination: true, - navigation: true, - autoplay: true, - mouseDragging: true, - slidesPerPage: 1, - slidesPerMove: 1, - orientation: 'horizontal' - } - ); - return ( - <> - - - The sun shines on the mountains and trees - Photo by Adam Kool on Unsplash - - - A waterfall in the middle of a forest - Photo by Thomas Kelly on Unsplash - - - The sun is setting over a lavender field - Photo by Leonard Cotte on Unsplash - - - A field of grass with the sun setting in the background - Photo by Sapan Patel on Unsplash - - - A scenic view of a mountain with clouds rolling in - Photo by V2osk on Unsplash - - - -
-
- - Loop - - - Show navigation - - - Show pagination - - - Autoplay (3s) - - - Mouse dragging - -
-
- - - - Horizontal - Vertical - -
-
- - - ); -}; +const App = () => ( + <> + + + The sun shines on the mountains and trees - Photo by Adam Kool on Unsplash + + + A waterfall in the middle of a forest - Photo by Thomas Kelly on Unsplash + + + The sun is setting over a lavender field - Photo by Leonard Cotte on Unsplash + + + A field of grass with the sun setting in the background - Photo by Sapan Patel on Unsplash + + + A scenic view of a mountain with clouds rolling in - Photo by V2osk on Unsplash + + + +); ``` - - ## Examples -### Multiple slides per view +### Pagination -Setting the attribute `slides-per-view` is it possible to specify how many items are shown at a given time. -Using this feature, it may be also useful to advance multiple slides at once, even though not strictly necessary. -This can be done by using the `slides-per-move` attribute. +Use the `pagination` attribute to show the total number of slides and the current slide as a set of interactive dots. ```html preview - - Slide 1 - Slide 2 - Slide 3 - Slide 4 - Slide 5 - Slide 6 + + + The sun shines on the mountains and trees - Photo by Adam Kool on Unsplash + + + A waterfall in the middle of a forest - Photo by Thomas Kelly on Unsplash + + + The sun is setting over a lavender field - Photo by Leonard Cotte on Unsplash + + + A field of grass with the sun setting in the background - Photo by Sapan Patel on Unsplash + + + A scenic view of a mountain with clouds rolling in - Photo by V2osk on Unsplash + + +``` + +### Navigation + +Use the `navigation` attribute to show previous and next buttons. + +```html preview + + + The sun shines on the mountains and trees - Photo by Adam Kool on Unsplash + + + A waterfall in the middle of a forest - Photo by Thomas Kelly on Unsplash + + + The sun is setting over a lavender field - Photo by Leonard Cotte on Unsplash + + + A field of grass with the sun setting in the background - Photo by Sapan Patel on Unsplash + + + A scenic view of a mountain with clouds rolling in - Photo by V2osk on Unsplash + + +``` + +### Looping + +By default, the carousel will not advanced beyond the first and last slides. You can change this behavior and force the carousel to "wrap" with the `loop` attribute. + +```html preview + + + The sun shines on the mountains and trees - Photo by Adam Kool on Unsplash + + + A waterfall in the middle of a forest - Photo by Thomas Kelly on Unsplash + + + The sun is setting over a lavender field - Photo by Leonard Cotte on Unsplash + + + A field of grass with the sun setting in the background - Photo by Sapan Patel on Unsplash + + + A scenic view of a mountain with clouds rolling in - Photo by V2osk on Unsplash + + +``` + +### Autoplay + +The carousel will automatically advance when the `autoplay` attribute is used. To change how long a slide is shown before advancing, set `autoplay-interval` to the desired number of milliseconds. For best results, use the `loop` attribute when autoplay is enabled. Note that autoplay will pause while the user interacts with the carousel. + +```html preview + + + The sun shines on the mountains and trees - Photo by Adam Kool on Unsplash + + + A waterfall in the middle of a forest - Photo by Thomas Kelly on Unsplash + + + The sun is setting over a lavender field - Photo by Leonard Cotte on Unsplash + + + A field of grass with the sun setting in the background - Photo by Sapan Patel on Unsplash + + + A scenic view of a mountain with clouds rolling in - Photo by V2osk on Unsplash + + +``` + +### Mouse Dragging + +The carousel uses [scroll snap](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Scroll_Snap) to position slides at various snap positions. This allows users to scroll through the slides very naturally, especially on touch devices. Unfortunately, desktop users won't be able to click and drag with a mouse, which can feel unnatural. Adding the `mouse-dragging` attribute can help with this. + +This example is best demonstrated using a mouse. Try clicking and dragging the slide to move it. Then toggle the switch and try again. + +```html preview +
+ + + The sun shines on the mountains and trees - Photo by Adam Kool on Unsplash + + + A waterfall in the middle of a forest - Photo by Thomas Kelly on Unsplash + + + The sun is setting over a lavender field - Photo by Leonard Cotte on Unsplash + + + A field of grass with the sun setting in the background - Photo by Sapan Patel on Unsplash + + + A scenic view of a mountain with clouds rolling in - Photo by V2osk on Unsplash + + + + + + Enable mouse dragging +
+ + +``` + +### Multiple Slides Per View + +The `slides-per-view` attribute makes it possible to display multiple slides at a time. You can also use the `slides-per-move` attribute to advance more than once slide at a time, if desired. + +```html preview + + Slide 1 + Slide 2 + Slide 3 + Slide 4 + Slide 5 + Slide 6 ``` @@ -281,66 +313,73 @@ import { SlCarousel, SlCarouselItem } from '@shoelace-style/shoelace/dist/react' const App = () => ( - Slide 1 - Slide 2 - Slide 3 - Slide 4 - Slide 5 - Slide 6 + Slide 1 + Slide 2 + Slide 3 + Slide 4 + Slide 5 + Slide 6 ); ``` -### Adding/removing slides +### Adding and Removing Slides -The content of the carousel can be changed by either appending or removing items, the carousel will update itself automatically. +The content of the carousel can be changed by appending or removing carousel items. The carousel will update itself automatically. ```html preview - Slide 1 - Slide 2 - Slide 3 + Slide 1 + Slide 2 + Slide 3 - +
Add slide Remove slide
+ + @@ -579,7 +626,7 @@ Use the `--aspect-ratio` custom property to customize the size of viewport in or ```jsx react import { useState } from 'react'; -import { SlCarousel, SlCarouselItem, SlDivider, SlSelect, SlMenuItem } from '@shoelace-style/shoelace/dist/react'; +import { SlCarousel, SlCarouselItem, SlDivider, SlSelect, SlOption } from '@shoelace-style/shoelace/dist/react'; const App = () => { const [aspectRatio, setAspectRatio] = useState('3/2'); @@ -627,9 +674,9 @@ const App = () => { value={aspectRatio} onSlChange={event => setAspectRatio(event.target.value)} > - 1 / 1 - 3 / 2 - 16 / 9 + 1 / 1 + 3 / 2 + 16 / 9 @@ -638,14 +685,12 @@ const App = () => { }; ``` -### Scroll hint +### Scroll Hint -Use `--scroll-padding` to add inline padding in horizontal carousels and block padding in vertical carousels. -Setting a padding, will make the closest slides visible, suggesting to the user that there are items that can -be scrolled. +Use the `--scroll-hint` attribute to add inline padding in horizontal carousels and block padding in vertical carousels. Setting a padding will make the closest slides slightly visible, hinting that there are more items in the carousel. ```html preview - + The sun shines on the mountains and trees - Photo by Adam Kool on Unsplash - - - - - ``` ```jsx react @@ -755,189 +786,9 @@ const App = () => { }; ``` -### Custom layout +### Gallery Example -The appearance of the carousel can be easily customized through its slots or `part` attributes. - -```html preview - - - The sun shines on the mountains and trees - Photo by Adam Kool on Unsplash - - - A waterfall in the middle of a forest - Photo by Thomas Kelly on Unsplash - - - The sun is setting over a lavender field - Photo by Leonard Cotte on Unsplash - - - A field of grass with the sun setting in the background - Photo by Sapan Patel on Unsplash - - - A scenic view of a mountain with clouds rolling in - Photo by V2osk on Unsplash - - - - - - - -``` - -```jsx react -import { SlCarousel, SlCarouselItem } from '@shoelace-style/shoelace/dist/react'; - -const css = ` - .custom-layout::part(base) { - grid-template-areas: - 'slides slides slides' - 'slides slides slides'; - } - - .custom-layout::part(pagination) { - position: absolute; - bottom: 0; - left: 0; - width: 100%; - padding: var(--sl-spacing-large); - background: linear-gradient(0deg, rgba(0, 0, 0, 0.8) 5%, rgba(0, 0, 0, 0.2) 75%, rgba(0, 0, 0, 0) 100%); - } - - .custom-layout::part(pagination-item) { - height: 5px; - width: var(--sl-spacing-large); - border-radius: var(--sl-border-radius-pill); - background-color: #fff; - } - - .custom-layout::part(pagination-item--active) { - background-color: var(--sl-color-primary-400); - width: var(--sl-spacing-x-large); - } - - .custom-layout::part(navigation-button) { - margin: var(--sl-spacing-large); - border-radius: var(--sl-border-radius-circle); - font-weight: var(--sl-font-weight-bold); - color: var(--sl-color-neutral-1000); - background: var(--sl-color-neutral-0); - opacity: 0.6; - transition: var(--sl-transition-medium) opacity; - } - - .custom-layout::part(navigation-button):focus, - .custom-layout::part(navigation-button):hover { - opacity: 1; - } -`; - -const App = () => ( - <> - - - The sun shines on the mountains and trees - Photo by Adam Kool on Unsplash - - - A waterfall in the middle of a forest - Photo by Thomas Kelly on Unsplash - - - The sun is setting over a lavender field - Photo by Leonard Cotte on Unsplash - - - A field of grass with the sun setting in the background - Photo by Sapan Patel on Unsplash - - - A scenic view of a mountain with clouds rolling in - Photo by V2osk on Unsplash - - - - - - - -); -``` - -### Gallery example - -The carousel has a set of API with which is possible to interact programmatically, for example it is possible to -use `next()` or `previous()` to go respectively to the next or the previous slide. - -When the active slide is changed, the `sl-slide-change` event is emitted providing the `index` of the slide. - -Using the API is possible to extend the carousel, for example by syncing the active slide with a set of thumbnails, like in the example below. +The carousel has a robust API that makes it possible to extend and customize. This example syncs the active slide with a set of thumbnails, effectively creating a gallery-style carousel. ```html preview @@ -972,6 +823,7 @@ Using the API is possible to extend the carousel, for example by syncing the act /> +
Thumbnail Photo by 1 @@ -981,6 +833,7 @@ Using the API is possible to extend the carousel, for example by syncing the act Thumbnail Photo by 5
+ +