🎠Valence Carousel

Last updated: 2.0.0 (22/01/2024)

This package is a Plugin package, meaning that it provides additional functionality that may not be needed by all projects. It should be used alongside @valence-ui/core and @valence-ui/utils. Don't know what this means?

The Valence Carousel is a custom horizontal carousel component designed for maximum usability in desktop and mobile environments. It allows a user to interact with it via the browser's native horizontal scroll, by clicking and dragging, and with the controls on either side. This component is based closely on the image carousel in the Instagram Threads app.

Installation & usage

npm install @valence-ui/carousel

import { Carousel, CarouselChildProps } from "@valence-ui/carousel";

function Demo() { 
  return (
    <Carousel>
      <CarouselChild 
        key={i}
      />
    </Carousel>
  )
}

function CarouselChild(props: CarouselChildProps) { 
  return ( 
    <div
      style={{
        backgroundColor: props.isActive ? "red" : undefined,
        outline: props.isNearest ? "1px solid red" : undefined,
      }}
    >
      Carousel Child
    </div>
  )
}

This example is an uncontrolled carousel. The Carousel package does not include a default child component, instead relying on a custom component that uses the CarouselChildProps. CarouselChildProps gives the isActive and isNearest props to the child, which can be used to influence style or behaviour.

The Carousel can also be used in a controlled manner, allowing higher-level components to know and/or control the active child:

import { Carousel, CarouselChildProps } from "@valence-ui/carousel";
import { useState } from "react";

function Demo() { 

  const [activeChild, setActiveChild] = useState(0);

  return (
    <Carousel
      activeChild={activeChild}
      setActiveChild={setActiveChild}
    >
      <CarouselChild 
        key={i}
      />
    </Carousel>
  )
}

// etc.

---

Props

Extends FlexProps.

Property	Type	Description
children (required)	ReactNode[]
allowDrag	boolean	Whether to allow the carousel content to be dragged on desktop. true on desktop devices by default.
showScrollbar	boolean	Whether to show the horizontal scrollbar. false by default.
snapToChildren	boolean	Whether to snap to the nearest child when no longer scrolling. true by default.
changeActiveOnScroll	boolean	Whether the active child should be changed during scroll. true by default.
contentProps	FlexProps	Optional props to pass to the content flex component.
activeChild	number	The active child of this carousel. For use when controlled.
setActiveChild	(index: number) => void	Sets the active child of this carousel. For use when controlled.
showControls	boolean	Whether to the carousel controls. true by default.
controlIcons	{ prev: ReactNode, next: ReactNode }	Optional overrides for the icons to use for the controls.
controlButtonProps	IconButtonProps	Optional props to pass to the control buttons.