Carousel
<mf-carousel> | MfCarousel
Carousels display an arbitrary number of content slides along a horizontal or vertical axis.
<mf-carousel pagination navigation mouse-dragging loop> <mf-carousel-item> <img alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)" src="/assets/examples/carousel/mountains.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)" src="/assets/examples/carousel/waterfall.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)" src="/assets/examples/carousel/sunset.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)" src="/assets/examples/carousel/field.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)" src="/assets/examples/carousel/valley.jpg" /> </mf-carousel-item> </mf-carousel>
import MfCarousel from 'maf-ui-kit/dist/react/carousel'; import MfCarouselItem from 'maf-ui-kit/dist/react/carousel-item'; const App = () => ( <> <MfCarousel pagination mouse-dragging> <MfCarouselItem> <img alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)" src="/assets/examples/carousel/mountains.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)" src="/assets/examples/carousel/waterfall.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)" src="/assets/examples/carousel/sunset.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)" src="/assets/examples/carousel/field.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)" src="/assets/examples/carousel/valley.jpg" /> </MfCarouselItem> </MfCarousel> </> );
Examples
Pagination
Use the pagination attribute to show the total number of slides and the current slide as a set
of interactive dots.
<mf-carousel pagination> <mf-carousel-item> <img alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)" src="/assets/examples/carousel/mountains.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)" src="/assets/examples/carousel/waterfall.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)" src="/assets/examples/carousel/sunset.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)" src="/assets/examples/carousel/field.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)" src="/assets/examples/carousel/valley.jpg" /> </mf-carousel-item> </mf-carousel>
import MfCarousel from 'maf-ui-kit/dist/react/carousel'; import MfCarouselItem from 'maf-ui-kit/dist/react/carousel-item'; const App = () => ( <MfCarousel pagination> <MfCarouselItem> <img alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)" src="/assets/examples/carousel/mountains.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)" src="/assets/examples/carousel/waterfall.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)" src="/assets/examples/carousel/sunset.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)" src="/assets/examples/carousel/field.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)" src="/assets/examples/carousel/valley.jpg" /> </MfCarouselItem> </MfCarousel> );
Navigation
Use the navigation attribute to show previous and next buttons.
<mf-carousel navigation> <mf-carousel-item> <img alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)" src="/assets/examples/carousel/mountains.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)" src="/assets/examples/carousel/waterfall.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)" src="/assets/examples/carousel/sunset.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)" src="/assets/examples/carousel/field.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)" src="/assets/examples/carousel/valley.jpg" /> </mf-carousel-item> </mf-carousel>
import MfCarousel from 'maf-ui-kit/dist/react/carousel'; import MfCarouselItem from 'maf-ui-kit/dist/react/carousel-item'; const App = () => ( <MfCarousel navigation> <MfCarouselItem> <img alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)" src="/assets/examples/carousel/mountains.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)" src="/assets/examples/carousel/waterfall.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)" src="/assets/examples/carousel/sunset.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)" src="/assets/examples/carousel/field.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)" src="/assets/examples/carousel/valley.jpg" /> </MfCarouselItem> </MfCarousel> );
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.
<mf-carousel loop navigation pagination> <mf-carousel-item> <img alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)" src="/assets/examples/carousel/mountains.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)" src="/assets/examples/carousel/waterfall.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)" src="/assets/examples/carousel/sunset.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)" src="/assets/examples/carousel/field.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)" src="/assets/examples/carousel/valley.jpg" /> </mf-carousel-item> </mf-carousel>
import MfCarousel from 'maf-ui-kit/dist/react/carousel'; import MfCarouselItem from 'maf-ui-kit/dist/react/carousel-item'; const App = () => ( <MfCarousel loop navigation pagination> <MfCarouselItem> <img alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)" src="/assets/examples/carousel/mountains.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)" src="/assets/examples/carousel/waterfall.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)" src="/assets/examples/carousel/sunset.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)" src="/assets/examples/carousel/field.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)" src="/assets/examples/carousel/valley.jpg" /> </MfCarouselItem> </MfCarousel> );
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.
<mf-carousel autoplay loop pagination> <mf-carousel-item> <img alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)" src="/assets/examples/carousel/mountains.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)" src="/assets/examples/carousel/waterfall.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)" src="/assets/examples/carousel/sunset.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)" src="/assets/examples/carousel/field.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)" src="/assets/examples/carousel/valley.jpg" /> </mf-carousel-item> </mf-carousel>
import MfCarousel from 'maf-ui-kit/dist/react/carousel'; import MfCarouselItem from 'maf-ui-kit/dist/react/carousel-item'; const App = () => ( <MfCarousel autoplay loop pagination> <MfCarouselItem> <img alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)" src="/assets/examples/carousel/mountains.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)" src="/assets/examples/carousel/waterfall.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)" src="/assets/examples/carousel/sunset.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)" src="/assets/examples/carousel/field.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)" src="/assets/examples/carousel/valley.jpg" /> </MfCarouselItem> </MfCarousel> );
Mouse Dragging
The carousel uses
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.
<div class="mouse-dragging"> <mf-carousel pagination> <mf-carousel-item> <img alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)" src="/assets/examples/carousel/mountains.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)" src="/assets/examples/carousel/waterfall.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)" src="/assets/examples/carousel/sunset.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)" src="/assets/examples/carousel/field.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)" src="/assets/examples/carousel/valley.jpg" /> </mf-carousel-item> </mf-carousel> <mf-divider></mf-divider> <mf-switch>Enable mouse dragging</mf-switch> </div> <script> const container = document.querySelector('.mouse-dragging'); const carousel = container.querySelector('mf-carousel'); const toggle = container.querySelector('mf-switch'); toggle.addEventListener('mf-change', () => { carousel.toggleAttribute('mouse-dragging', toggle.checked); }); </script>
import { useState } from 'react'; import MfCarousel from 'maf-ui-kit/dist/react/carousel'; import MfCarouselItem from 'maf-ui-kit/dist/react/carousel-item'; import MfDivider from 'maf-ui-kit/dist/react/divider'; import MfSwitch from 'maf-ui-kit/dist/react/switch'; const App = () => { const [isEnabled, setIsEnabled] = useState(false); return ( <> <MfCarousel navigation mouseDragging={isEnabled}> <MfCarouselItem> <img alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)" src="/assets/examples/carousel/mountains.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)" src="/assets/examples/carousel/waterfall.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)" src="/assets/examples/carousel/sunset.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)" src="/assets/examples/carousel/field.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)" src="/assets/examples/carousel/valley.jpg" /> </MfCarouselItem> </MfCarousel> <MfDivider></MfDivider> <MfSwitch checked={isEnabled} onMfInput={() => setIsEnabled(!isEnabled)}> Enable mouse dragging </MfSwitch> </> ); };
Multiple Mfides Per View
The slides-per-page 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.
<mf-carousel navigation pagination slides-per-page="2" slides-per-move="2"> <mf-carousel-item style="background: var(--mf-color-red-200);">Mfide 1</mf-carousel-item> <mf-carousel-item style="background: var(--mf-color-orange-200);">Mfide 2</mf-carousel-item> <mf-carousel-item style="background: var(--mf-color-yellow-200);">Mfide 3</mf-carousel-item> <mf-carousel-item style="background: var(--mf-color-green-200);">Mfide 4</mf-carousel-item> <mf-carousel-item style="background: var(--mf-color-blue-200);">Mfide 5</mf-carousel-item> <mf-carousel-item style="background: var(--mf-color-violet-200);">Mfide 6</mf-carousel-item> </mf-carousel>
import MfCarousel from 'maf-ui-kit/dist/react/carousel'; import MfCarouselItem from 'maf-ui-kit/dist/react/carousel-item'; const App = () => ( <MfCarousel navigation pagination slidesPerPage={2} slidesPerMove={2}> <MfCarouselItem style={{ background: 'var(--mf-color-red-200)' }}>Mfide 1</MfCarouselItem> <MfCarouselItem style={{ background: 'var(--mf-color-orange-200)' }}>Mfide 2</MfCarouselItem> <MfCarouselItem style={{ background: 'var(--mf-color-yellow-200)' }}>Mfide 3</MfCarouselItem> <MfCarouselItem style={{ background: 'var(--mf-color-green-200)' }}>Mfide 4</MfCarouselItem> <MfCarouselItem style={{ background: 'var(--mf-color-blue-200)' }}>Mfide 5</MfCarouselItem> <MfCarouselItem style={{ background: 'var(--mf-color-violet-200)' }}>Mfide 6</MfCarouselItem> </MfCarousel> );
Adding and Removing Mfides
The content of the carousel can be changed by adding or removing carousel items. The carousel will update itself automatically.
<mf-carousel class="dynamic-carousel" pagination navigation> <mf-carousel-item style="background: var(--mf-color-red-200)">Mfide 1</mf-carousel-item> <mf-carousel-item style="background: var(--mf-color-orange-200)">Mfide 2</mf-carousel-item> <mf-carousel-item style="background: var(--mf-color-yellow-200)">Mfide 3</mf-carousel-item> </mf-carousel> <div class="carousel-options"> <mf-button id="dynamic-add">Add slide</mf-button> <mf-button id="dynamic-remove">Remove slide</mf-button> </div> <style> .dynamic-carousel { --aspect-ratio: 3 / 2; } .dynamic-carousel ~ .carousel-options { display: flex; justify-content: center; gap: var(--mf-spacing-x-small); margin-top: var(--mf-spacing-large); } .dynamic-carousel mf-carousel-item { flex: 0 0 100%; display: flex; align-items: center; justify-content: center; font-size: var(--mf-font-size-2x-large); } </style> <script> (() => { const dynamicCarousel = document.querySelector('.dynamic-carousel'); const dynamicAdd = document.querySelector('#dynamic-add'); const dynamicRemove = document.querySelector('#dynamic-remove'); const colors = ['red', 'orange', 'yellow', 'green', 'blue', 'violet']; let colorIndex = 2; const addMfide = () => { const slide = document.createElement('mf-carousel-item'); const color = colors[++colorIndex % colors.length]; slide.innerText = `Mfide ${dynamicCarousel.children.length + 1}`; slide.style.setProperty('background', `var(--mf-color-${color}-200)`); dynamicCarousel.appendChild(slide); dynamicRemove.disabled = false; }; const removeMfide = () => { const slide = dynamicCarousel.children[dynamicCarousel.children.length - 1]; const numMfides = dynamicCarousel.querySelectorAll('mf-carousel-item').length; if (numMfides > 1) { slide.remove(); colorIndex--; } dynamicRemove.disabled = numMfides - 1 <= 1; }; dynamicAdd.addEventListener('click', addMfide); dynamicRemove.addEventListener('click', removeMfide); })(); </script>
import { useState } from 'react'; import MfCarousel from 'maf-ui-kit/dist/react/carousel'; import MfCarouselItem from 'maf-ui-kit/dist/react/carousel-item'; const css = ` .dynamic-carousel { --aspect-ratio: 3 / 2; } .dynamic-carousel ~ .carousel-options { display: flex; justify-content: center; margin-top: var(--mf-spacing-large); } .dynamic-carousel mf-carousel-item { flex: 0 0 100%; display: flex; align-items: center; justify-content: center; color: white; font-size: var(--mf-font-size-2x-large); } `; const App = () => { const [slides, setMfides] = useState(['#204ed8', '#be133d', '#6e28d9']); const colors = ['red', 'orange', 'yellow', 'green', 'blue', 'violet']; const addMfide = () => { setMfides([...slides, getRandomColor()]); }; const removeMfide = () => { setMfides(slides.slice(0, -1)); }; return ( <> <MfCarousel className="dynamic-carousel" pagination navigation> {slides.map((color, i) => ( <MfCarouselItem style={{ background: colors[i % colors.length }}> Mfide {i} </MfCarouselItem> ))} </MfCarousel> <div className="carousel-options"> <MfButton onClick={addMfide}>Add slide</MfButton> <MfButton onClick={removeMfide}>Remove slide</MfButton> </div> <style>{css}</style> </> ); };
Vertical Scrolling
Setting the orientation attribute to vertical will render the carousel in a
vertical layout. If the content of your slides vary in height, you will need to set amn explicit
height or max-height on the carousel using CSS.
<mf-carousel class="vertical" pagination orientation="vertical"> <mf-carousel-item> <img alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)" src="/assets/examples/carousel/mountains.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)" src="/assets/examples/carousel/waterfall.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)" src="/assets/examples/carousel/sunset.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)" src="/assets/examples/carousel/field.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)" src="/assets/examples/carousel/valley.jpg" /> </mf-carousel-item> </mf-carousel> <style> .vertical { max-height: 400px; } .vertical::part(base) { grid-template-areas: 'slides slides pagination'; } .vertical::part(pagination) { flex-direction: column; } .vertical::part(navigation) { transform: rotate(90deg); display: flex; } </style>
import MfCarousel from 'maf-ui-kit/dist/react/carousel'; import MfCarouselItem from 'maf-ui-kit/dist/react/carousel-item'; const css = ` .vertical { max-height: 400px; } .vertical::part(base) { grid-template-areas: 'slides slides pagination'; } .vertical::part(pagination) { flex-direction: column; } .vertical::part(navigation) { transform: rotate(90deg); display: flex; } `; const App = () => ( <> <MfCarousel className="vertical" loop pagination orientation="vertical"> <MfCarouselItem> <img alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)" src="/assets/examples/carousel/mountains.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)" src="/assets/examples/carousel/waterfall.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)" src="/assets/examples/carousel/sunset.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)" src="/assets/examples/carousel/field.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)" src="/assets/examples/carousel/valley.jpg" /> </MfCarouselItem> </MfCarousel> <style>{css}</style> </> );
Aspect Ratio
Use the --aspect-ratio custom property to customize the size of the carousel’s viewport from
the default value of 16/9.
<mf-carousel class="aspect-ratio" navigation pagination style="--aspect-ratio: 3/2;"> <mf-carousel-item> <img alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)" src="/assets/examples/carousel/mountains.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)" src="/assets/examples/carousel/waterfall.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)" src="/assets/examples/carousel/sunset.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)" src="/assets/examples/carousel/field.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)" src="/assets/examples/carousel/valley.jpg" /> </mf-carousel-item> </mf-carousel> <mf-divider></mf-divider> <mf-select label="Aspect ratio" name="aspect" value="3/2"> <mf-option value="1/1">1/1</mf-option> <mf-option value="3/2">3/2</mf-option> <mf-option value="16/9">16/9</mf-option> </mf-select> <script> (() => { const carousel = document.querySelector('mf-carousel.aspect-ratio'); const aspectRatio = document.querySelector('mf-select[name="aspect"]'); aspectRatio.addEventListener('mf-change', () => { carousel.style.setProperty('--aspect-ratio', aspectRatio.value); }); })(); </script>
import { useState } from 'react'; import MfCarousel from 'maf-ui-kit/dist/react/carousel'; import MfCarouselItem from 'maf-ui-kit/dist/react/carousel-item'; import MfDivider from 'maf-ui-kit/dist/react/divider'; import MfSelect from 'maf-ui-kit/dist/react/select'; import MfOption from 'maf-ui-kit/dist/react/option'; const App = () => { const [aspectRatio, setAspectRatio] = useState('3/2'); return ( <> <MfCarousel className="aspect-ratio" navigation pagination style={{ '--aspect-ratio': aspectRatio }}> <MfCarouselItem> <img alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)" src="/assets/examples/carousel/mountains.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)" src="/assets/examples/carousel/waterfall.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)" src="/assets/examples/carousel/sunset.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)" src="/assets/examples/carousel/field.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)" src="/assets/examples/carousel/valley.jpg" /> </MfCarouselItem> </MfCarousel> <MfDivider /> <MfSelect label="Aspect ratio" name="aspect" value={aspectRatio} onMfChange={event => setAspectRatio(event.target.value)} > <MfOption value="1 / 1">1 / 1</MfOption> <MfOption value="3 / 2">3 / 2</MfOption> <MfOption value="16 / 9">16 / 9</MfOption> </MfSelect> <style>{css}</style> </> ); };
Scroll Hint
Use the --scroll-hint custom property to add inline padding in horizontal carousels and block
padding in vertical carousels. This will make the closest slides slightly visible, hinting that there are
more items in the carousel.
<mf-carousel class="scroll-hint" pagination style="--scroll-hint: 10%;"> <mf-carousel-item> <img alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)" src="/assets/examples/carousel/mountains.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)" src="/assets/examples/carousel/waterfall.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)" src="/assets/examples/carousel/sunset.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)" src="/assets/examples/carousel/field.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)" src="/assets/examples/carousel/valley.jpg" /> </mf-carousel-item> </mf-carousel>
import { useState } from 'react'; import MfCarousel from 'maf-ui-kit/dist/react/carousel'; import MfCarouselItem from 'maf-ui-kit/dist/react/carousel-item'; import MfDivider from 'maf-ui-kit/dist/react/divider'; import MfRange from 'maf-ui-kit/dist/react/range'; const App = () => ( <> <MfCarousel className="scroll-hint" pagination style={{ '--scroll-hint': '10%' }}> <MfCarouselItem> <img alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)" src="/assets/examples/carousel/mountains.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)" src="/assets/examples/carousel/waterfall.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)" src="/assets/examples/carousel/sunset.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)" src="/assets/examples/carousel/field.jpg" /> </MfCarouselItem> <MfCarouselItem> <img alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)" src="/assets/examples/carousel/valley.jpg" /> </MfCarouselItem> </MfCarousel> </> );
Gallery Example
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.
<mf-carousel class="carousel-thumbnails" navigation loop> <mf-carousel-item> <img alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)" src="/assets/examples/carousel/mountains.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)" src="/assets/examples/carousel/waterfall.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)" src="/assets/examples/carousel/sunset.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)" src="/assets/examples/carousel/field.jpg" /> </mf-carousel-item> <mf-carousel-item> <img alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)" src="/assets/examples/carousel/valley.jpg" /> </mf-carousel-item> </mf-carousel> <div class="thumbnails"> <div class="thumbnails__scroller"> <img alt="Thumbnail by 1" class="thumbnails__image active" src="/assets/examples/carousel/mountains.jpg" /> <img alt="Thumbnail by 2" class="thumbnails__image" src="/assets/examples/carousel/waterfall.jpg" /> <img alt="Thumbnail by 3" class="thumbnails__image" src="/assets/examples/carousel/sunset.jpg" /> <img alt="Thumbnail by 4" class="thumbnails__image" src="/assets/examples/carousel/field.jpg" /> <img alt="Thumbnail by 5" class="thumbnails__image" src="/assets/examples/carousel/valley.jpg" /> </div> </div> <style> .carousel-thumbnails { --slide-aspect-ratio: 3 / 2; } .thumbnails { display: flex; justify-content: center; } .thumbnails__scroller { display: flex; gap: var(--mf-spacing-small); overflow-x: auto; scrollbar-width: none; scroll-behavior: smooth; scroll-padding: var(--mf-spacing-small); } .thumbnails__scroller::-webkit-scrollbar { display: none; } .thumbnails__image { width: 64px; height: 64px; object-fit: cover; opacity: 0.3; will-change: opacity; transition: 250ms opacity; cursor: pointer; } .thumbnails__image.active { opacity: 1; } </style> <script> { const carousel = document.querySelector('.carousel-thumbnails'); const scroller = document.querySelector('.thumbnails__scroller'); const thumbnails = document.querySelectorAll('.thumbnails__image'); scroller.addEventListener('click', e => { const target = e.target; if (target.matches('.thumbnails__image')) { const index = [...thumbnails].indexOf(target); carousel.goToMfide(index); } }); carousel.addEventListener('mf-slide-change', e => { const slideIndex = e.detail.index; [...thumbnails].forEach((thumb, i) => { thumb.classList.toggle('active', i === slideIndex); if (i === slideIndex) { thumb.scrollIntoView({ block: 'nearest' }); } }); }); } </script>
import { useRef } from 'react'; import MfCarousel from 'maf-ui-kit/dist/react/carousel'; import MfCarouselItem from 'maf-ui-kit/dist/react/carousel-item'; import MfDivider from 'maf-ui-kit/dist/react/divider'; import MfRange from 'maf-ui-kit/dist/react/range'; const css = ` .carousel-thumbnails { --slide-aspect-ratio: 3 / 2; } .thumbnails { display: flex; justify-content: center; } .thumbnails__scroller { display: flex; gap: var(--mf-spacing-small); overflow-x: auto; scrollbar-width: none; scroll-behavior: smooth; scroll-padding: var(--mf-spacing-small); } .thumbnails__scroller::-webkit-scrollbar { display: none; } .thumbnails__image { width: 64px; height: 64px; object-fit: cover; opacity: 0.3; will-change: opacity; transition: 250ms opacity; cursor: pointer; } .thumbnails__image.active { opacity: 1; } `; const images = [ { src: '/assets/examples/carousel/mountains.jpg', alt: 'The sun shines on the mountains and trees (by Adam Kool on Unsplash' }, { src: '/assets/examples/carousel/waterfall.jpg', alt: 'A waterfall in the middle of a forest (by Thomas Kelly on Unsplash' }, { src: '/assets/examples/carousel/sunset.jpg', alt: 'The sun is setting over a lavender field (by Leonard Cotte on Unsplash' }, { src: '/assets/examples/carousel/field.jpg', alt: 'A field of grass with the sun setting in the background (by Sapan Patel on Unsplash' }, { src: '/assets/examples/carousel/valley.jpg', alt: 'A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash' } ]; const App = () => { const carouselRef = useRef(); const thumbnailsRef = useRef(); const [currentMfide, setCurrentMfide] = useState(0); useEffect(() => { const thumbnails = Array.from(thumbnailsRef.current.querySelectorAll('.thumbnails__image')); thumbnails[currentMfide]..scrollIntoView({ block: 'nearest' }); }, [currentMfide]); const handleThumbnailClick = (index) => { carouselRef.current.goToMfide(index); } const handleMfideChange = (event) => { const slideIndex = e.detail.index; setCurrentMfide(slideIndex); } return ( <> <MfCarousel className="carousel-thumbnails" navigation loop onMfMfideChange={handleMfideChange}> {images.map({ src, alt }) => ( <MfCarouselItem> <img alt={alt} src={src} /> </MfCarouselItem> )} </MfCarousel> <div class="thumbnails"> <div class="thumbnails__scroller"> {images.map({ src, alt }, i) => ( <img alt={`Thumbnail by ${i + 1}`} className={`thumbnails__image ${i === currentMfide ? 'active' : ''}`} onClick={() => handleThumbnailClick(i)} src={src} /> )} </div> </div> <style>{css}</style> </> ); };
Importing
If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.
To import this component from the CDN using a script tag:
<script type="module" src="https://cdn.jsdelivr.net/npm/maf-ui-kit@0.0.1/cdn/components/carousel/carousel.js"></script>
To import this component from the CDN using a JavaScript import:
import 'https://cdn.jsdelivr.net/npm/maf-ui-kit@0.0.1/cdn/components/carousel/carousel.js';
To import this component using a bundler:
import 'maf-ui-kit/dist/components/carousel/carousel.js';
To import this component as a React component:
import MfCarousel from 'maf-ui-kit/dist/react/carousel';
slots
| Name | Description |
|---|---|
| (default) | The carousel’s main content, one or more <mf-carousel-item> elements. |
next-icon
|
Optional next icon to use instead of the default. Works best with <mf-icon>.
|
previous-icon
|
Optional previous icon to use instead of the default. Works best with <mf-icon>.
|
Learn more about using slots.
Properties
| Name | Description | Reflects | Type | Default |
|---|---|---|---|---|
loop
|
When set, allows the user to navigate the carousel in the same direction indefinitely. |
|
boolean
|
false
|
navigation
|
When set, show the carousel’s navigation. |
|
boolean
|
false
|
pagination
|
When set, show the carousel’s pagination indicators. |
|
boolean
|
false
|
autoplay
|
When set, the slides will scroll automatically when the user is not interacting with them. |
|
boolean
|
false
|
autoplayInterval
autoplay-interval
|
Specifies the amount of time, in milliseconds, between each automatic scroll. |
number
|
3000
|
|
slidesPerPage
slides-per-page
|
Specifies how many slides should be shown at a given time. |
number
|
1
|
|
slidesPerMove
slides-per-move
|
Specifies the number of slides the carousel will advance when scrolling, useful when specifying a
slides-per-page greater than one. It can’t be higher than slides-per-page.
|
number
|
1
|
|
orientation
|
Specifies the orientation in which the carousel will lay out. |
'horizontal' | 'vertical'
|
'horizontal'
|
|
mouseDragging
mouse-dragging
|
When set, it is possible to scroll through the slides by dragging them with the mouse. |
|
boolean
|
false
|
updateComplete |
A read-only promise that resolves when the component has finished updating. |
Learn more about attributes and properties.
Events
| Name | React Event | Description | Event Detail |
|---|---|---|---|
mf-slide-change |
onMfSlideChange |
Emitted when the active slide changes. |
{ index: number, slide: MfCarouselItem }
|
Learn more about events.
Methods
| Name | Description | Arguments |
|---|---|---|
previous() |
Move the carousel backward by slides-per-move slides. |
behavior: ScrollBehavior
|
next() |
Move the carousel forward by slides-per-move slides. |
behavior: ScrollBehavior
|
goToMfide() |
Scrolls the carousel to the slide specified by index. |
index: number, behavior: ScrollBehavior
|
Learn more about methods.
Custom Properties
| Name | Description | Default |
|---|---|---|
--slide-gap |
The space between each slide. | |
--aspect-ratio |
The aspect ratio of each slide. | 16/9 |
--scroll-hint |
The amount of padding to apply to the scroll area, allowing adjacent slides to become partially visible as a scroll hint. |
Learn more about customizing CSS custom properties.
Parts
| Name | Description |
|---|---|
base |
The carousel’s internal wrapper. |
scroll-container |
The scroll container that wraps the slides. |
pagination |
The pagination indicators wrapper. |
pagination-item |
The pagination indicator. |
pagination-item--active |
Applied when the item is active. |
navigation |
The navigation wrapper. |
navigation-button |
The navigation button. |
navigation-button--previous |
Applied to the previous button. |
navigation-button--next |
Applied to the next button. |
Learn more about customizing CSS parts.
Dependencies
This component automatically imports the following dependencies.
<mf-icon>