react-cscarousel

A re-usable responsive React carousel component as used in https://blythemillsheds.co.uk/.

Notes

- Lazy loading: Files are lazy loaded to make the component more responsive, and avoid downloading files which are not displayed.
- File order: Files are displayed in the order they are presented in the files array prop. This means that the file at index 0 is the first displayed file in the carousel.
- Thumbnails: If used alongside a list of thumbnails, it is recommended that the thumbnail images are created separately and with a reduced size. Otherwise this will stop the lazy loading aspect of the carousel.
- Styles: Don't forget to import "react-cscarousel/dist/styles.scss" otherwise the styling won't work!

Exported Functions

- ShowFileFromIndex: Programatically scroll the carousel to the file at the specified index.

Dependencies

- React 19+ (peer).
- react-cslib (peer): https://github.com/sidfishus/react-cslib.
- @sidfishus/cslib (peer): https://github.com/sidfishus/cslib.

To Install

npm install react-cscarousel react-cslib @sidfishus/cslib

props

- files: FILE_T[]: The list of files to display.
- selectedId: bigint|null: The ID of the selected file. If null, defaults to the first file.
- setSelectedFile: SetSelectedFileFunc: Callback to update the selected file.
- fileDir?: string: An optional source file directory which is prefixed to the file source for brevity if specified.
- autoChangeMs?: number: If specified, automatically scrolls to the next image on the right every autoChangeMs milliseconds.
- loadFileOverride?: (url: string) => Promise: Override loading files. Useful if the file get URL requires an auth header and must be manually loaded.
- shouldLoad: boolean: Override whether or not files should be loaded.
- autoLoadLeftAndRightFiles?: boolean: Loads the files to the immediate left and right hand sides of the current displayed file. Defaults to true if not specified.
- additionalFileClass?: ((isLoading: boolean)=>string*: Additional file class name.
- additionalFileContainerClass?: string: Additional file container class name.
- loadingFileUrl: string: URL to the loading image.
- chevronUrl?: string: URL to the chevron image, if the ability to scroll files left and right is enabled.
- overrideLeftChevronClass?: string: Override the class of the left chevron.
- overrideRightChevronClass?: string: Override the class of the right chevron.
- ref: RefObject: The ref of the carousel div (instanciated via React.useRef).

Example

See https://github.com/sidfishus/react-cscarousel/blob/main/src/TestApp.tsx.

Index.tsx
``

files={bmsImages}
selectedId={imageId}
setSelectedFile={setGallerySelectedImage}
shouldLoad={true}
fileDir={"/src/images/bms/"}
additionalFileClass={(isLoading)=> isLoading ? "BMSFileLoading" : "BMSFile"}
additionalFileContainerClass={"BMSFileContainer"}
loadingFileUrl={"Spinner-1s-300px.svg"}
chevronUrl={"../orange-chevron-left.svg"}
ref={carouselRef}
autoChangeMs={10000}
overrideLeftChevronClass={"BMSFileLeftChevron"}
overrideRightChevronClass={"BMSFileRightChevron"}
/>

fileDir={"/src/images/bms/"}
files={thumbnails}
selectedIndex={(imageId === null ? 0 : bmsImages.findIndex(img => img.id === imageId))}
onClick={idx => ShowFileFromIndex(carouselRef.current,idx,"smooth")}
/>

`

Index.scss
`
.BMSFileContainer {
padding-left: 10px;
padding-right: 10px;
padding-top: 2px;
padding-bottom: 2px;
}

.BMSFile,.BMSFileLoading {
border-radius: 5px;

border: white solid 1.5px;
box-shadow: 0 0 0 1px black;
}

.BMSFileLeftChevron,.BMSFileRightChevron {
width: 100px;
position: absolute;
z-index: 5;

top: calc(50% - (100px / 2));

cursor: pointer;
}

.BMSFileLeftChevron {
left: 30px;
}

.BMSFileRightChevron {
right: 30px;
transform: rotate(-180deg);
}

.BMSFileLeftChevron:active,.BMSFileRightChevron:active {
opacity: 25%;
}
``

Produces:
!Carousel with thumbnails