react-snaplist-carousel
v4.6.0TypeScript
A light, pure React, no dependencies and flexible carousel. A modern way to do a classic thing.
2.1K/weekUpdated 2 years agoMITUnpacked: 3.6 MB
Published by luispuig
npm install react-snaplist-carousel
react-snaplist-carousel
A modern way to do a classic thing.
- Less than 3K gzipped size.
- Made 100% in React, no porting.
- No dependencies.
- Typescript ready.
- Using it in production.
- Using native browser snap option.
- No magic, you get the control thanks to the hooks.
Demo
Install
``bash`
npm install --save react-snaplist-carousel
`tsx`
import {
SnapList,
SnapItem,
useVisibleElements,
useScroll,
} from 'react-snaplist-carousel';
Basic Example
`tsx
import * as React from 'react';
import { SnapList, SnapItem } from 'react-snaplist-carousel';
const MyItem = ({ children }) => (
{children}
);
export const App = () => (
);
`
A11y Example
`tsx
import * as React from 'react';
import { SnapList, SnapItem } from 'react-snaplist-carousel';
const MyItem = React.forwardRef(({ children, ...props }, ref) => (
ref={ref}
{...props}
>
{children}
));
export const App = () => {
const snapList = useRef(null);
const lastSnapItem = useRef(null);
const goToSnapItem = useScroll({ ref: snapList });
return (
tabIndex={0} // so it can receive focus and can be scrolled with keyboard
role="region" // context for screen readers
aria-label="my awesome snaplist" // for screen readers to read out loud on focus
>
goToSnapItem(4);
lastSnapItem.current?.focus();
}}
>
go to last item
Item 4
);
};
`
Advanced Example
`tsx
import React, { useRef } from 'react';
import {
SnapList,
SnapItem,
useVisibleElements,
useScroll,
useDragToScroll,
isTouchDevice,
} from 'react-snaplist-carousel';
const MyItem = ({ onClick, children, visible }) => (
width: '60vw',
height: 200,
background: visible ? '#bce6fe' : '#cccccc',
cursor: visible ? 'default' : 'pointer',
}}
onClick={onClick}
>
{children}
);
export const App = () => {
const snapList = useRef(null);
const visible = useVisibleElements(
{ debounce: 10, ref: snapList },
([element]) => element,
);
const goToSnapItem = useScroll({ ref: snapList });
const { isDragging } = useDragToScroll({ ref: snapList });
return (
Item 0
Item 1
Item 2
Item 3
Item 4
);
};
`
Options
$3
- direction { horizontal | vertical }: Scroll direction. \*disableScroll
- { boolean | undefined }: Disable the native scroll on swipe or mouse wheel.snapType
- { mandatory | proximity }. Optional (default mandatory): Change how items are snapped inside the container.width
- { string | undefined }: Width CSS propertyheight
- { string | undefined }: Height CSS propertyscrollPadding
- { {hideScrollbar
top?: string;
right?: string;
bottom?: string;
left?: string;
} | undefined }: Use this to configure the space to see from the previous/next hidden element. See scroll-padding for more information
- { boolean }. Optional (default true): Hide/show scrollbars.ref
- { React.RefObject\className
- { string | undefined }: 🚑Please, use this only in case of emergency. It allows you to add/overwrite/extend all the CSS properties. If you need this, please consider opening an issue or contribute with a PR to cover your use case.
\* _Required fields_
$3
- snapAlign { start | center | end | none }: The box’s snap position when the scroll stops. See scroll-snap-align for more information \*disableScroll
- { boolean | undefined }: Avoid the scroll to "pass over" possible snap positions. See scroll-snap-stop for more informationwidth
- { string | undefined }: Width CSS propertyheight
- { string | undefined }: Height CSS propertymargin
- { {className
top?: string;
right?: string;
bottom?: string;
left?: string;
} | undefined }: The margin is used to set the separation between the items. You can use different margin for the first and last item to get better results.
- { string | undefined }: 🚑Please, use this only in case of emergency. It allows you to add/overwrite/extend all the CSS properties. If you need this, please consider opening an issue or contribute with a PR to cover your use case.
\* _Required fields_
$3
`jsx
const snapList = useRef(null);
const goToElement = useScroll({ ref: snapList });
return (
goTo(0)}>Item 0
goTo(1)}>Item 1
);
`
Response
- A function (element:number, options?: { animationEnabled: boolean}) => void to scroll to the element. The animationEnabled is true by default. It can be use to scroll to a component when mounting it.
Arguments
- ref: { React.RefObject\
\* _Required fields_
$3
`jsx
const snapList = useRef(null);
const selected = useVisibleElements(
{ ref: snapList, debounce: 10 },
elements => elements[0],
);
const goToElement = useScroll({ ref: snapList });
React.useEffect(() => {
// scroll instantly on component did mount
goToElement(1, { animationEnabled: false });
}, []);
return (
style={{
backgroundColor: selected === 0 ? 'papayawhip' : null,
}}
>
Item 0
style={{
backgroundColor: selected === 1 ? 'papayawhip' : null,
}}
>
Item 1
);
`
Arguments
-
: { React.RefObject\ } \*
- debounce: { number }. Optional (default 10). The time that the scroll is stopped before firing the visible elements check.
- selectorFunction: { (element:number[], elementInCenter: number | null) => any }. This selector gets an array of the visible elements as an argument and the return value will be returned by the useVisibleElements. Use this function to add some logic like select only the first one, calculate if there hidden elements before or later, etc... \*\* _Required fields_
Tip
Use many times
useVisibleElements hook with different debounce values for different purposes. For instance with a SnapList to select one option, one with debounce 10 for the slider dots animation or the selected option background and another one with debounce 100 to fire a select sideEffect.$3
> Thanks @danieljb for the contribution
`jsx
const snapList = useRef(null);
const selected = useVisibleElements(
{ ref: snapList, debounce: 10 },
elements => elements[0],
);const { isDragging } = useDragToScroll({ ref: snapList, disable: false });
return (
<>
{isDragging ? 'Dragging' : 'No dragging'}
style={{
backgroundColor: selected === 0 ? 'papayawhip' : null,
}}
>
Item 0
style={{
backgroundColor: selected === 1 ? 'papayawhip' : null,
}}
>
Item 1