A Generic carousel UI component for React using Material UI.
Installations
npm install react-material-ui-carousel
Developer
Learus
Developer Guide
Module System
CommonJS
Min. Node Version
Typescript Support
Yes
Node Version
NPM Version
Statistics
555 Stars
167 Commits
219 Forks
6 Watching
15 Branches
16 Contributors
Updated on 26 Nov 2024
Bundle Size
118.58 kB
Minified
38.15 kB
Minified + Gzipped
Languages
TypeScript (100%)
Total Downloads
Cumulative downloads
Total Downloads
12,032,201
Last day
0.3%
18,920
Compared to previous day
Last week
5.7%
97,125
Compared to previous week
Last month
17.5%
425,964
Compared to previous month
Last year
16.6%
4,436,413
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Peer Dependencies
7
React Material UI Carousel
Description
A Generic, extendible Carousel UI component for React using Material UI
It switches between given children using a smooth animation.
Provides next and previous buttons.
Also provides interactible bullet indicators.
Live Demo
Take a look at this interactible Live Demo
Installation
1npm install react-material-ui-carousel --save
Note:
You will need to have Material UI installed, in order to use this library/component
1npm install @mui/material 2npm install @mui/icons-material 3npm install @mui/styles
Other Versions
1# Version 2 with MUI 4 2npm install react-material-ui-carousel@v2 --save 3npm install @material-ui/core 4npm install @material-ui/icons 5 6 7# Version 2 with MUI 5 support 8npm install react-material-ui-carousel@v2mui5 --save
Usage Example
1import React from 'react'; 2import Carousel from 'react-material-ui-carousel' 3import { Paper, Button } from '@mui/material' 4 5function Example(props) 6{ 7 var items = [ 8 { 9 name: "Random Name #1", 10 description: "Probably the most random thing you have ever seen!" 11 }, 12 { 13 name: "Random Name #2", 14 description: "Hello World!" 15 } 16 ] 17 18 return ( 19 <Carousel> 20 { 21 items.map( (item, i) => <Item key={i} item={item} /> ) 22 } 23 </Carousel> 24 ) 25} 26 27function Item(props) 28{ 29 return ( 30 <Paper> 31 <h2>{props.item.name}</h2> 32 <p>{props.item.description}</p> 33 34 <Button className="CheckButton"> 35 Check it out! 36 </Button> 37 </Paper> 38 ) 39}
Next & Prev Usage
1 <Carousel 2 next={ (next, active) => console.log(`we left ${active}, and are now at ${next}`); } 3 prev={ (prev, active) => console.log(`we left ${active}, and are now at ${prev}`); } 4 > 5 {...} 6 </Carousel> 7 8 // OR 9 10 <Carousel 11 next={ () => {/* Do stuff */} } 12 prev={ () => {/* Do other stuff */} } 13 > 14 {...} 15 </Carousel> 16 17 // And so on...
Note: onChange
works in a similar fashion. See Props below.
Customizing Navigation
Navigation Buttons - Customizing the default solution
These are the props that are used to directly customize the Carousel's default buttons:
- NextIcon
- PrevIcon
- navButtonsProps
- navButtonsWrapperProps
- fullHeightHover
Example #1
Say we don't like the default icons used for the next and prev buttons and want to change them to be an MUI Icon or an image of our own.
1 2 3import RandomIcon from '@@mui/icons-material/Random'; // Note: this doesn't exist 4 5<Carousel 6 NextIcon={<RandomIcon/>} 7 PrevIcon={<RandomIcon/>} 8 // OR 9 NextIcon={<img src="http://random.com/next"/>} 10 PrevIcon={<img src="http://random.com/prev"/>} 11> 12 {...} 13</Carousel>
The NextIcon
and PrevIcon
is of type ReactNode
, meaning it can be any JSX element or a string. Note: Extra styling may be needed when using those props.
Example #2
Let's now say we don't like the default graphite background of the buttons, nor do we like the fact that it is round.
We also want to place them under the main Carousel, and finally remove the arrows and have "next" and "prev" accordingly to each button.
A very important note here, is that any styles specified by the user DO NOT OVERRIDE THE EXISTING STYLES. They work in tandem with them. That means, that if you want to change, or get rid of a CSS attribute you will have to override it or unset it. The Default styles are given at the end of this section, and are part of the code.
1<Carousel 2 fullHeightHover={false} // We want the nav buttons wrapper to only be as big as the button element is 3 navButtonsProps={{ // Change the colors and radius of the actual buttons. THIS STYLES BOTH BUTTONS 4 style: { 5 backgroundColor: 'cornflowerblue', 6 borderRadius: 0 7 } 8 }} 9 navButtonsWrapperProps={{ // Move the buttons to the bottom. Unsetting top here to override default style. 10 style: { 11 bottom: '0', 12 top: 'unset' 13 } 14 }} 15 NextIcon='next' // Change the "inside" of the next button to "next" 16 PrevIcon='prev' // Change the "inside of the prev button to "prev" 17> 18 {...} 19</Carousel>
Of course, extra styling to the button wrappers, or indicators might be needed to achieve exactly what we may be looking for. Note: You can also use className
to change the styles externally.
Customizing the navigation buttons directly
Do directly customize/change the navigation buttons NavButton
prop, that allows the user to take complete control of the components rendered as the navigation buttons. It should be used like this:
Example
1import {Button} from '@mui/material'; 2 3<Carousel 4 NavButton={({onClick, className, style, next, prev}) => { 5 // Other logic 6 7 return ( 8 <Button onClick={onClick} className={className} style={style}> 9 {next && "Next"} 10 {prev && "Previous"} 11 </Button> 12 ) 13 }} 14> 15 {...} 16</Carousel>
Parameters Explanation
onClick
: The function that handles actual navigation. If you do not add this to your component, the buttons will not work.className
: The className given by the carousel component. This is used to handle Visible/Invisible, hover, and user specified styles (e.g. from navButtonProps). Apply it to the outmost element.style
: The style given by the carousel component. Used to give any user specified styles (e.g. from navButtonProps).next
: Boolean value that specifies whether this is the next button.prev
: Boolean value that specifies whether this is the prev button.
The prop value must be a function that returns a component. All parameters are optional as far as styling goes (not functionality), but it is advised you use them as shown above.
As implied, any className
s or style
s specified in the navButtonsProps will only be used iff you apply the given className
and style
parameters.
Customizing the Indicators
There are 4 props that handle indicator customization
- IndicatorIcon
- activeIndicatorIconButtonProps
- indicatorIconButtonProps
- indicatorContainerProps
Example
Let's say we would like to change the indicator icon from a circle to a something else, for example a little house
1import Home from '@mui/icons-material/Home'; 2 3<Carousel 4 IndicatorIcon={<Home/>} 5 // OR 6 IndicatorIcon={<img src="http://random.com/home"/>} 7> 8 {...} 9</Carousel>
The IndicatorIcon
works the same way as the NextIcon
and PrevIcon
prop.
Example #2
Let's say we would like to have an array to icons like numbers, to order the elements of my carousel numerically. Let's do this!
1const anArrayOfNumbers = [<img src="http://random.com/one"/>, 2 <img src="http://random.com/two"/>, 3 <img src="http://random.com/three"/> 4 ]; 5 6<Carousel 7 IndicatorIcon={anArrayOfNumbers} 8> 9 {...} 10</Carousel>
Example #3
Now we want to do more complex customizations. Specifically:
- More distance between the indicator icons
- Change the background color of the active indicator to
red
- Change the color of all indicators to
blue
- Move the indicators to the right side of the carousel
- Move the indicators to be further away down from the carousel
We are going to use all props to style the indicators
1import Home from '@mui/icons-material/Home'; 2 3<Carousel 4 IndicatorIcon={<Home/>} // Previous Example 5 indicatorIconButtonProps={{ 6 style: { 7 padding: '10px', // 1 8 color: 'blue' // 3 9 } 10 }} 11 activeIndicatorIconButtonProps={{ 12 style: { 13 backgroundColor: 'red' // 2 14 } 15 }} 16 indicatorContainerProps={{ 17 style: { 18 marginTop: '50px', // 5 19 textAlign: 'right' // 4 20 } 21 22 }} 23> 24 {...} 25</Carousel>
As before, you can use className
to style the elements externally.
Default Styles
Giving the default styles in pseudo-code.
Navigation Buttons
1{ 2 buttonWrapper: { 3 position: "absolute", 4 height: "100px", 5 backgroundColor: "transparent", 6 top: "calc(50% - 70px)", 7 '&:hover': { 8 '& $button': { 9 backgroundColor: "black", 10 filter: "brightness(120%)", 11 opacity: "0.4" 12 } 13 } 14 }, 15 fullHeightHoverWrapper: { 16 height: "100%", 17 top: "0" 18 }, 19 buttonVisible:{ 20 opacity: "1" 21 }, 22 buttonHidden:{ 23 opacity: "0", 24 }, 25 button: { 26 margin: "0 10px", 27 position: "relative", 28 backgroundColor: "#494949", 29 top: "calc(50% - 20px) !important", 30 color: "white", 31 fontSize: "30px", 32 transition: "200ms", 33 cursor: "pointer", 34 '&:hover': { 35 opacity: "0.6 !important" 36 }, 37 }, 38 // Applies to the "next" button wrapper 39 next: { 40 right: 0 41 }, 42 // Applies to the "prev" button wrapper 43 prev: { 44 left: 0 45 } 46}
Indicators
1{ 2 indicators: { 3 width: "100%", 4 marginTop: "10px", 5 textAlign: "center" 6 }, 7 indicator: { 8 cursor: "pointer", 9 transition: "200ms", 10 padding: 0, 11 color: "#afafaf", 12 '&:hover': { 13 color: "#1f1f1f" 14 }, 15 '&:active': { 16 color: "#1f1f1f" 17 } 18 }, 19 indicatorIcon: { 20 fontSize: "15px", 21 }, 22 // Applies to the active indicator 23 active: { 24 color: "#494949" 25 } 26}
Props
Prop name | Type | Default | Description |
---|---|---|---|
sx | SxProps<Theme> | {} | Defines sx props, that will be inserted into the Carousel 's root element |
className | string | "" | Defines custom class name(s), that will be added to Carousel element |
height | number | string | undefined | Defines the carousel's height in px . If this is not set, the carousel's height will be the height of its children. If it is not set, the carousel's height will be the same as the current active child. |
index | number | 0 | Defines which child (assuming there are more than 1 children) will be displayed. Next and Previous Buttons as well as Indicators will work normally after the first render. When this prop is updated the carousel will display the chosen child. Use this prop to programmatically set the active child. If (index > children.length) then if (strictIndexing) index = last element. index |
strictIndexing | boolean | true | Defines whether index can be bigger than children length |
autoPlay | boolean | true | Defines if the component will auto scroll between children |
stopAutoPlayOnHover | boolean | true | Defines if auto scrolling will continue while mousing over carousel |
interval | number | 4000 | Defines the interval in ms between active child changes (autoPlay) |
animation | "fade" | "slide" | "fade" | Defines the animation style of the Carousel |
duration | number | 500 | Defines the duration of the animations. |
swipe | boolean | true | Defines if swiping left and right (in touch devices) triggers next and prev behaviour |
indicators | boolean | true | Defines the existence of bullet indicators |
navButtonsAlwaysVisible | boolean | false | Defines if the next/previous buttons will always be visible or not |
navButtonsAlwaysInvisible | boolean | false | Defines if the next/previous buttons will always be invisible or not |
cycleNavigation | boolean | true | Defines if the next button will be visible on the last slide, and the previous button on the first slide. Auto-play also stops on the last slide. Indicators continue to work normally. |
fullHeightHover | boolean | true | Defines if the the next/previous button wrappers will cover the full height of the Item element and show buttons on full height hover |
navButtonsWrapperProps | {className: string, style: React.CSSProperties} & React.AriaAttributes | undefined | Used to customize the div surrounding the nav IconButtons . Use this to position the buttons onto, below, outside, e.t.c. the carousel. Tip: Check the default styles below. |
navButtonsProps | {className: string, style: React.CSSProperties} & React.AriaAttributes | undefined | Used to customize the actual nav IconButton s |
NextIcon | ReactNode | <NavigateNextIcon/> | Defines the element inside the nav "next" IconButton . Refer to MaterialUI Button Documentation for more examples. It is advised to use Material UI Icons, but you could use any element (<img/> , <div/> , ...) you like. |
PrevIcon | ReactNode | <NavigateNextIcon/> | Defines the element inside the nav "prev" IconButton . Refer to MaterialUI Button Documentation for more examples. It is advised to use Material UI Icons, but you could use any element (<img/> , <div/> , ...) you like. |
NavButton | ({onClick, className, style, prev, next}: {onClick: Function, className: string, style: React.CSSProperties, next: boolean, prev: boolean}) => ReactNode | undefined | Gives full control of the nav buttons. Should return a button that uses the given onClick . Works in tandem with all other customization options (navButtonsProps , navButtonsWrapperProps , navButtonsAlwaysVisible , navButtonsAlwaysInvisible , fullHeightHover , ...). Refer to the example section for more information. |
indicatorIconButtonProps | {className: string, style: React.CSSProperties} & React.AriaAttributes | undefined | Used to customize all indicator IconButton s. Additive to activeIndicatorIconButtonProps . Any aria-label property used will be rendered with the indicator index next to it. e.g. {'aria-label': 'indicator'} --> 'indicator 1' |
activeIndicatorIconButtonProps | {className: string, style: React.CSSProperties} & React.AriaAttributes | undefined | Used to customize the active indicator IconButton . Additive to indicatorIconButtonProps . |
indicatorContainerProps | {className: string, style: React.CSSProperties} & React.AriaAttributes | undefined | Used to customize the indicators container/wrapper. |
IndicatorIcon | ReactNode | <FiberManualRecordIcon size='small' className={classes.indicatorIcon}/> | Defines the element inside the indicator IconButton s Refer to MaterialUI Button Documentation for more examples. It is advised to use Material UI Icons, but you could use any element (<img/> , <div/> , ...) you like. |
onChange | (now?: number, previous?: number) => any | () => {} | Function that is called after internal setActive() method. The setActive() method is called when the next and previous buttons are pressed, when an indicator is pressed, or when the index prop changes. First argument is the child we are going to display, while the second argument is the child that was previously displayed. Will be called in conjunction with and after next and prev props if defined. It will not get called in first render, except if changeOnFirstRender is defined |
changeOnFirstRender | boolean | false | Defines if onChange prop will be called when the carousel renders for the first time. In componentDidMount |
next | (now?: number, previous?: number) => any | () => {} | Function that is called after internal next() method. First argument is the child we are going to display, while the second argument is the child that was previously displayed |
prev | (now?: number, previous?: number) => any | () => {} | Function that is called after internal prev() method. First argument is the child we are going to display, while the second argument is the child that was previously displayed |
License
The MIT License.
Author
No vulnerabilities found.
Reason
no binaries found in the repo
Reason
license file detected
Details
- Info: project has a license file: LICENSE.txt:0
- Info: FSF or OSI recognized license: MIT License: LICENSE.txt:0
Reason
Found 1/9 approved changesets -- score normalized to 1
Reason
0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
branch protection not enabled on development/release branches
Details
- Warn: branch protection not enabled for branch 'master'
- Warn: branch protection not enabled for branch 'version2mui5'
- Warn: branch protection not enabled for branch 'version2'
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
- Warn: 0 commits out of 23 are checked with a SAST tool
Reason
64 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-67hx-6x53-jw92
- Warn: Project is vulnerable to: GHSA-whgm-jr23-g3j9
- Warn: Project is vulnerable to: GHSA-wf5p-g6vw-rhxx
- Warn: Project is vulnerable to: GHSA-qwcr-r2fm-qrc7
- Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg
- Warn: Project is vulnerable to: GHSA-x9w5-v3q2-3rhw
- Warn: Project is vulnerable to: GHSA-w8qv-6jwh-64r5
- Warn: Project is vulnerable to: GHSA-pxg6-pf52-xh8x
- Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275
- Warn: Project is vulnerable to: GHSA-w573-4hg7-7wgq
- Warn: Project is vulnerable to: GHSA-phwq-j96m-2c2q
- Warn: Project is vulnerable to: GHSA-ghr5-ch3p-vcr6
- Warn: Project is vulnerable to: GHSA-434g-2637-qmqr
- Warn: Project is vulnerable to: GHSA-49q7-c7j4-3p7m
- Warn: Project is vulnerable to: GHSA-977x-g7h5-7qgw
- Warn: Project is vulnerable to: GHSA-f7q4-pwc6-w24p
- Warn: Project is vulnerable to: GHSA-fc9h-whq2-v747
- Warn: Project is vulnerable to: GHSA-4gmj-3p3h-gm8h
- Warn: Project is vulnerable to: GHSA-rv95-896h-c2vc
- Warn: Project is vulnerable to: GHSA-qw6h-vgh9-j6wx
- Warn: Project is vulnerable to: GHSA-jchw-25xp-jwwc
- Warn: Project is vulnerable to: GHSA-cxjh-pqwp-8mfp
- Warn: Project is vulnerable to: GHSA-8mmm-9v2q-x3f9
- Warn: Project is vulnerable to: GHSA-c7qv-q95q-8v27
- Warn: Project is vulnerable to: GHSA-33f9-j839-rf8h
- Warn: Project is vulnerable to: GHSA-c36v-fmgq-m8hx
- Warn: Project is vulnerable to: GHSA-78xj-cgh5-2h22
- Warn: Project is vulnerable to: GHSA-2p57-rm9w-gvfp
- Warn: Project is vulnerable to: GHSA-9c47-m6qq-7p4h
- Warn: Project is vulnerable to: GHSA-76p3-8jx3-jpfq
- Warn: Project is vulnerable to: GHSA-3rfm-jhwj-7488
- Warn: Project is vulnerable to: GHSA-hhq3-ff78-jv3g
- Warn: Project is vulnerable to: GHSA-35jh-r3h4-6jhm
- Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv
- Warn: Project is vulnerable to: GHSA-f8q6-p94x-37v3
- Warn: Project is vulnerable to: GHSA-5rrq-pxf6-6jx5
- Warn: Project is vulnerable to: GHSA-8fr3-hfg3-gpgp
- Warn: Project is vulnerable to: GHSA-gf8q-jrpm-jvxq
- Warn: Project is vulnerable to: GHSA-2r2c-g63r-vccr
- Warn: Project is vulnerable to: GHSA-cfm4-qjh2-4765
- Warn: Project is vulnerable to: GHSA-x4jg-mjrx-434g
- Warn: Project is vulnerable to: GHSA-rp65-9cf3-cjxr
- Warn: Project is vulnerable to: GHSA-9wv6-86v2-598j
- Warn: Project is vulnerable to: GHSA-7fh5-64p2-3v2j
- Warn: Project is vulnerable to: GHSA-gcx4-mw62-g8wm
- Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw
- Warn: Project is vulnerable to: GHSA-m6fv-jmcg-4jfg
- Warn: Project is vulnerable to: GHSA-cm22-4g7w-348p
- Warn: Project is vulnerable to: GHSA-g4rg-993r-mgx7
- Warn: Project is vulnerable to: GHSA-f5x3-32g6-xq36
- Warn: Project is vulnerable to: GHSA-4wf5-vphf-c2xc
- Warn: Project is vulnerable to: GHSA-72xf-g2v4-qvf3
- Warn: Project is vulnerable to: GHSA-wr3j-pwj9-hqq6
- Warn: Project is vulnerable to: GHSA-j8xg-fqg3-53r7
- Warn: Project is vulnerable to: GHSA-3h5v-q93c-6h6q
- Warn: Project is vulnerable to: GHSA-93q8-gq69-wqmw
- Warn: Project is vulnerable to: GHSA-fwr7-v2mv-hh25
- Warn: Project is vulnerable to: GHSA-cwfw-4gq5-mrqx
- Warn: Project is vulnerable to: GHSA-g95f-p29q-9xw4
- Warn: Project is vulnerable to: GHSA-6h5x-7c5m-7cr7
- Warn: Project is vulnerable to: GHSA-896r-f27r-55mw
- Warn: Project is vulnerable to: GHSA-qrpm-p2h7-hrv2
- Warn: Project is vulnerable to: GHSA-hrpp-h998-j3pp
- Warn: Project is vulnerable to: GHSA-p8p7-x288-28g6
Score
1.9
/10
Last Scanned on 2024-11-25
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn MoreOther packages similar to react-material-ui-carousel
@mui/material
Material UI is an open-source React component library that implements Google's Material Design. It's comprehensive and can be used in production out of the box.
@mui/icons-material
Material Design icons distributed as SVG React components.
@material-ui/icons
Material Design Svg Icons converted to Material-UI React components.
@mui/styled-engine
styled() API wrapper package for emotion.