Carousel
Installation
Package depends on @mantine/core
and @mantine/hooks
.
Install with yarn:
Install with npm:
Usage
@mantine/carousel
package is based on embla carousel,
it supports most of its features:
Options
Size and gap
Set slideSize
and slideGap
on Carousel
component to control size and gap of every slide:
You can also control size and gap of each slide individually by setting size
and gap
props
on Carousel.Slide
component:
Responsive styles
breakpoints
prop works the same way as in SimpleGrid component.
You can use maxWidth
or minWidth
to define slideSize
and slideGap
at given breakpoints:
Drag free
dragFree
will disable slides snap points – user will be able to stop dragging at any position:
Vertical orientation
Carousel with orientation="vertical"
requires height
prop to be set:
Controls icons
You can replace default next/previous controls icons with any React nodes:
100% height
Set height="100%"
to make Carousel take 100% height of the container. Note that in this case:
- container element must have
display: flex
styles - carousel root element must have
flex: 1
styles - container element must have fixed height
Get embla instance
You can get embla instance with getEmblaApi
prop.
You will be able enhance carousel with additional logic after that using embla api methods:
Embla plugins
Set plugins
prop to enhance carousel with embla plugins.
Note that plugins are not installed with @mantine/carousel
package and you will need to
install them on your side.
Example with autoplay plugin:
Styles API
Carousel
supports Styles API, you can customize styles of any inner element.
Indicator styles
Hide inactive controls
Show controls on hover
Examples
Images carousel
Cards carousel
Carousel container animation offset
Embla carousel only reads slides positions and sizes upon initialization. When you are using Carousel component inside animated component you may experience an issue with incorrect slides offset after animation finishes.
Example of incorrect slides offset calculation (scroll though slides):
To solve this issue use useAnimationOffsetEffect
hook exported from @mantine/carousel
package.
It accepts embla instance as first argument and transition duration as second:
Carousel component props
Name | Type | Description |
---|---|---|
align | number | "center" | "end" | "start" | Determines how slides will be aligned relative to the container. Use number between 0-1 to align slides based on percentage, where 0.5 equals 50% |
breakpoints | CarouselBreakpoint[] | Control slideSize and slideGap at different viewport sizes |
children | ReactNode | <Carousel.Slide /> components |
containScroll | "" | "trimSnaps" | "keepSnaps" | Clear leading and trailing empty space that causes excessive scrolling. Use trimSnaps to only use snap points that trigger scrolling or keepSnaps to keep them. |
controlSize | number | Previous/next controls size in px |
controlsOffset | number | "xs" | "sm" | "md" | "lg" | "xl" | Key of theme.spacing or number to set space between next/previous control and carousel boundary |
dragFree | boolean | Determines whether momentum scrolling should be enabled, false by default |
draggable | boolean | Determines whether carousel can be scrolled with mouse and touch interactions, true by default |
getEmblaApi | (embla: EmblaCarouselType) => void | Get embla API as ref |
height | Height<string | number> | Slides container height, required for vertical orientation |
inViewThreshold | number | Choose a fraction representing the percentage portion of a slide that needs to be visible in order to be considered in view. For example, 0.5 equals 50%. |
includeGapInSize | boolean | Determines whether gap should be treated as part of the slide size, true by default |
initialSlide | number | Index of initial slide |
loop | boolean | Enables infinite looping. Automatically falls back to false if slide content isn't enough to loop. |
nextControlIcon | ReactNode | Icon of next control |
nextControlLabel | string | Next control aria-label |
onNextSlide | () => void | Called when user clicks next button |
onPreviousSlide | () => void | Called when user clicks previous button |
onSlideChange | (index: number) => void | Called with slide index when slide changes |
orientation | "horizontal" | "vertical" | Carousel orientation, horizontal by default |
plugins | CreatePluginType<LoosePluginType, {}>[] | An array of embla plugins |
previousControlIcon | ReactNode | Previous control icon |
previousControlLabel | string | Previous control aria-label |
skipSnaps | boolean | Allow the carousel to skip scroll snaps if it's dragged vigorously. Note that this option will be ignored if the dragFree option is set to true, false by default |
slideGap | number | "xs" | "sm" | "md" | "lg" | "xl" | Key of theme.spacing or number to set gap between slides in px |
slideSize | string | number | Slide width, defaults to 100%, examples: 200px, 50% |
slidesToScroll | number | "auto" | Number of slides that should be scrolled with next/previous buttons |
speed | number | Adjusts scroll speed when triggered by any of the methods. Higher numbers enables faster scrolling. |
withControls | boolean | Determines whether next/previous controls should be displayed, true by default |
withIndicators | boolean | Determines whether indicators should be displayed, false by default |
withKeyboardEvents | boolean | Determines whether arrow key should switch slides, true by default |
Carousel.Slide component props
Name | Type | Description |
---|---|---|
children | ReactNode | Slide content |
gap | number | "xs" | "sm" | "md" | "lg" | "xl" | Key of theme.spacing or number to set gap between slides in px |
size | string | number | Slide width, defaults to 100%, examples: 200px, 50% |
Carousel component Styles API
Name | Static selector | Description |
---|---|---|
root | .mantine-Carousel-root | Root element |
slide | .mantine-Carousel-slide | Slide root element |
container | .mantine-Carousel-container | Slides container |
viewport | .mantine-Carousel-viewport | Main element, contains slides container and all controls |
controls | .mantine-Carousel-controls | Next/previous controls container |
control | .mantine-Carousel-control | Next/previous control |
indicators | .mantine-Carousel-indicators | Indicators container |
indicator | .mantine-Carousel-indicator | Indicator button |