ScrollShadow

Apply visual shadows to indicate scrollable content overflow with automatic detection of scroll position.

Usage

1import { ScrollShadow } from "@lenso/ui";

1"use client";2
3import { ScrollShadow } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5
6const styles = stylex.create({7  root: { width: "100%", maxWidth: { default: null, "@media (min-width: 640px)": 384 } },8  scroll: { maxHeight: 240, padding: 16 },9  paragraphs: { display: "flex", flexDirection: "column", gap: 16 },10});11export function Default() {12  return (13    <div {...stylex.props(styles.root)}>14      <ScrollShadow tabIndex={0} aria-label="Scrollable sample text" xstyle={styles.scroll}>15        <div {...stylex.props(styles.paragraphs)}>16          {Array.from({ length: 10 }, (_, index) => (17            <p key={index}>18              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non19              risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam.20              Morbi accumsan cursus enim, sed ultricies sapien.21            </p>22          ))}23        </div>24      </ScrollShadow>25    </div>26  );27}28export default Default;

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Examples

Orientation

1"use client";2// Adapted from HeroUI v3.2.6 (Apache-2.0).3import { Card, ScrollShadow } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5const images = [6  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/robot1.jpeg",7  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/avocado.jpeg",8  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/oranges.jpeg",9];10const styles = stylex.create({11  root: { width: "100%", maxWidth: { default: null, "@media (min-width: 640px)": 384 } },12  vertical: { marginBottom: 32, width: "100%" },13  heading: { marginBottom: 8, fontSize: 14, lineHeight: "20px", fontWeight: 600 },14  card: { width: "100%", padding: 0 },15  verticalScroll: { maxHeight: 240, padding: 16 },16  horizontalScroll: { padding: 16 },17  paragraphs: { display: "flex", flexDirection: "column", gap: 16 },18  cards: { display: "flex", flexDirection: "row", gap: 16 },19  item: { display: "flex", minWidth: 200, flexDirection: "row", gap: 12, padding: 4 },20  image: {21    aspectRatio: "1",22    width: { default: 64, "@media (min-width: 640px)": 80 },23    height: { default: 64, "@media (min-width: 640px)": 80 },24    flexShrink: 0,25    borderRadius: "var(--radius-xl)",26    objectFit: "cover",27    userSelect: "none",28  },29  text: { display: "flex", flex: 1, flexDirection: "column", justifyContent: "center", gap: 4 },30  title: { fontSize: 14 },31  description: { fontSize: 12 },32});33export default function Orientation() {34  return (35    <div {...stylex.props(styles.root)}>36      <div {...stylex.props(styles.vertical)}>37        <h4 {...stylex.props(styles.heading)}>Vertical</h4>38        <Card xstyle={styles.card}>39          <ScrollShadow40            tabIndex={0}41            aria-label="Vertical sample"42            xstyle={styles.verticalScroll}43            orientation="vertical"44          >45            <div {...stylex.props(styles.paragraphs)}>46              {Array.from({ length: 10 }, (_, index) => (47                <p key={index}>48                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non49                  risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor50                  quam. Morbi accumsan cursus enim, sed ultricies sapien.51                </p>52              ))}53            </div>54          </ScrollShadow>55        </Card>56      </div>57      <div>58        <h4 {...stylex.props(styles.heading)}>Horizontal</h4>59        <Card xstyle={styles.card}>60          <ScrollShadow61            tabIndex={0}62            aria-label="Horizontal cards"63            xstyle={styles.horizontalScroll}64            orientation="horizontal"65          >66            <div {...stylex.props(styles.cards)}>67              {Array.from({ length: 10 }, (_, index) => (68                <Card key={index} xstyle={styles.item} variant="transparent">69                  <img70                    alt="Lorem Card"71                    {...stylex.props(styles.image)}72                    loading="lazy"73                    src={images[index % images.length]}74                  />75                  <div {...stylex.props(styles.text)}>76                    <Card.Title xstyle={styles.title}>Bridging the Future</Card.Title>77                    <Card.Description xstyle={styles.description}>Today, 6:30 PM</Card.Description>78                  </div>79                </Card>80              ))}81            </div>82          </ScrollShadow>83        </Card>84      </div>85    </div>86  );87}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Shadow Size

1"use client";2// Adapted from HeroUI v3.2.6 (Apache-2.0).3import { ScrollShadow } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5const styles = stylex.create({6  root: { width: "100%", maxWidth: { default: null, "@media (min-width: 640px)": 384 } },7  scroll: { maxHeight: 240, padding: 16 },8  paragraphs: { display: "flex", flexDirection: "column", gap: 16 },9});10export default function CustomSize() {11  return (12    <div {...stylex.props(styles.root)}>13      <ScrollShadow14        size={80}15        tabIndex={0}16        aria-label="Scrollable sample text"17        xstyle={styles.scroll}18      >19        <div {...stylex.props(styles.paragraphs)}>20          {Array.from({ length: 10 }, (_, index) => (21            <p key={index}>22              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non23              risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam.24              Morbi accumsan cursus enim, sed ultricies sapien.25            </p>26          ))}27        </div>28      </ScrollShadow>29    </div>30  );31}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

With Card

1"use client";2// Adapted from HeroUI v3.2.6 (Apache-2.0).3import { Button, Card, ScrollShadow } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5const styles = stylex.create({6  card: { maxWidth: 400 },7  content: { padding: 0 },8  scroll: { height: 300, paddingInline: 16 },9  paragraphs: { display: "flex", flexDirection: "column", gap: 16 },10  footer: { marginTop: 16, display: "flex", flexDirection: "row", gap: 8 },11  button: { width: "100%" },12});13export default function WithCard() {14  return (15    <Card xstyle={styles.card}>16      <Card.Header>17        <Card.Title>Terms and Conditions</Card.Title>18        <Card.Description>Please review before proceeding</Card.Description>19      </Card.Header>20      <Card.Content xstyle={styles.content}>21        <ScrollShadow22          tabIndex={0}23          aria-label="Terms and Conditions"24          xstyle={styles.scroll}25          size={80}26        >27          <div {...stylex.props(styles.paragraphs)}>28            {Array.from({ length: 10 }, (_, index) => (29              <p key={index}>30                Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non31                risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor32                quam. Morbi accumsan cursus enim, sed ultricies sapien.33              </p>34            ))}35          </div>36        </ScrollShadow>37      </Card.Content>38      <Card.Footer xstyle={styles.footer}>39        <Button xstyle={styles.button} variant="secondary">40          Cancel41        </Button>42        <Button xstyle={styles.button}>Accept</Button>43      </Card.Footer>44    </Card>45  );46}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Hide Scroll Bar

1"use client";2// Adapted from HeroUI v3.2.6 (Apache-2.0).3import { ScrollShadow } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5const styles = stylex.create({6  root: { width: "100%", maxWidth: { default: null, "@media (min-width: 640px)": 384 } },7  scroll: { maxHeight: 240, padding: 16 },8  paragraphs: { display: "flex", flexDirection: "column", gap: 16 },9});10export default function HideScrollBar() {11  return (12    <div {...stylex.props(styles.root)}>13      <ScrollShadow14        hideScrollBar15        tabIndex={0}16        aria-label="Scrollable sample text"17        xstyle={styles.scroll}18      >19        <div {...stylex.props(styles.paragraphs)}>20          {Array.from({ length: 10 }, (_, index) => (21            <p key={index}>22              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non23              risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam.24              Morbi accumsan cursus enim, sed ultricies sapien.25            </p>26          ))}27        </div>28      </ScrollShadow>29    </div>30  );31}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Visibility Change

1"use client";2// Adapted from HeroUI v3.2.6 (Apache-2.0).3import { Card, ScrollShadow, type ScrollShadowVisibility } from "@lenso/ui";4import { useState } from "react";5import * as stylex from "@stylexjs/stylex";6const images = [7  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/robot1.jpeg",8  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/avocado.jpeg",9  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/oranges.jpeg",10];11const styles = stylex.create({12  root: { width: "100%", maxWidth: { default: null, "@media (min-width: 640px)": 384 } },13  section: { display: "flex", flexDirection: "column", gap: 8 },14  vertical: { marginBottom: 32 },15  status: { borderRadius: "var(--radius)", backgroundColor: "var(--default)", padding: 16 },16  statusText: { fontSize: 14, lineHeight: "20px", fontWeight: 600 },17  verticalScroll: { maxHeight: 240, padding: 16 },18  horizontalScroll: { padding: 16 },19  paragraphs: { display: "flex", flexDirection: "column", gap: 16 },20  cards: { display: "flex", flexDirection: "row", gap: 16 },21  item: { display: "flex", minWidth: 200, flexDirection: "row", gap: 12, padding: 4 },22  image: {23    aspectRatio: "1",24    width: { default: 64, "@media (min-width: 640px)": 80 },25    height: { default: 64, "@media (min-width: 640px)": 80 },26    flexShrink: 0,27    borderRadius: "var(--radius-xl)",28    objectFit: "cover",29    userSelect: "none",30  },31  text: { display: "flex", flex: 1, flexDirection: "column", justifyContent: "center", gap: 4 },32  title: { fontSize: 14 },33  description: { fontSize: 12 },34});35export default function VisibilityChange() {36  const [verticalState, setVerticalState] = useState<ScrollShadowVisibility>("none");37  const [horizontalState, setHorizontalState] = useState<ScrollShadowVisibility>("none");38  return (39    <div {...stylex.props(styles.root)}>40      <div {...stylex.props(styles.section, styles.vertical)}>41        <div {...stylex.props(styles.status)}>42          <p {...stylex.props(styles.statusText)}>Vertical Shadow State: {verticalState}</p>43        </div>44        <ScrollShadow45          tabIndex={0}46          aria-label="Vertical sample"47          xstyle={styles.verticalScroll}48          orientation="vertical"49          onVisibilityChange={setVerticalState}50        >51          <div {...stylex.props(styles.paragraphs)}>52            {Array.from({ length: 10 }, (_, index) => (53              <p key={index}>54                Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non55                risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor56                quam. Morbi accumsan cursus enim, sed ultricies sapien.57              </p>58            ))}59          </div>60        </ScrollShadow>61      </div>62      <div {...stylex.props(styles.section)}>63        <div {...stylex.props(styles.status)}>64          <p {...stylex.props(styles.statusText)}>Horizontal Shadow State: {horizontalState}</p>65        </div>66        <ScrollShadow67          tabIndex={0}68          aria-label="Horizontal cards"69          xstyle={styles.horizontalScroll}70          orientation="horizontal"71          onVisibilityChange={setHorizontalState}72        >73          <div {...stylex.props(styles.cards)}>74            {Array.from({ length: 10 }, (_, index) => (75              <Card key={index} xstyle={styles.item} variant="transparent">76                <img77                  alt="Lorem Card"78                  {...stylex.props(styles.image)}79                  loading="lazy"80                  src={images[index % images.length]}81                />82                <div {...stylex.props(styles.text)}>83                  <Card.Title xstyle={styles.title}>Bridging the Future</Card.Title>84                  <Card.Description xstyle={styles.description}>Today, 6:30 PM</Card.Description>85                </div>86              </Card>87            ))}88          </div>89        </ScrollShadow>90      </div>91    </div>92  );93}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Customization

Tailwind CSS

1"use client";2// Adapted from HeroUI v3.2.6 (Apache-2.0).3import { ScrollShadow } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5const entries = [6  "Reviewed quarterly goals with the design team.",7  "Shipped dark mode tokens to production.",8  "Merged accessibility fixes for form fields.",9  "Published updated component documentation.",10  "Scheduled performance audit for next sprint.",11  "Added scroll shadow demos to the docs site.",12];13const styles = stylex.create({14  root: { width: "100%", maxWidth: { default: null, "@media (min-width: 640px)": 384 } },15  scroll: {16    maxHeight: 192,17    borderRadius: "var(--radius-xl)",18    border: "1px solid color-mix(in oklab, var(--border) 80%, transparent)",19    backgroundImage:20      "linear-gradient(to bottom, light-dark(oklch(98.5% 0 0 / .9), oklch(20.5% 0 0 / .8)), light-dark(white, oklch(20.5% 0 0)))",21    padding: 16,22    boxShadow: "0 0 0 1px light-dark(rgb(0 0 0 / .05), rgb(255 255 255 / .1))",23  },24  entries: { display: "flex", flexDirection: "column", gap: 12 },25  entry: {26    fontSize: 14,27    lineHeight: 1.625,28    color: "light-dark(oklch(43.9% 0 0), oklch(70.8% 0 0))",29  },30});31export function CustomStyles() {32  return (33    <div {...stylex.props(styles.root)}>34      <ScrollShadow35        hideScrollBar36        tabIndex={0}37        aria-label="Recent activity"38        xstyle={styles.scroll}39        size={48}40        variant="fade"41      >42        <div {...stylex.props(styles.entries)}>43          {entries.map((entry) => (44            <p key={entry} {...stylex.props(styles.entry)}>45              {entry}46            </p>47          ))}48        </div>49      </ScrollShadow>50    </div>51  );52}53export default CustomStyles;

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Global CSS

To customize the ScrollShadow component classes, you can use the @layer components directive. Learn more.

1@layer components {2  .scroll-shadow {3    @apply rounded-xl border border-default-200;4  }5
6  .scroll-shadow--vertical {7    @apply pr-2; /* Add padding for custom scrollbar styling */8  }9
10  .scroll-shadow--horizontal {11    @apply pb-2;12  }13}

Styling Reference

HeroUI follows the BEM methodology to ensure component variants and states are reusable and easy to customize.

CSS Classes

The ScrollShadow component uses these CSS classes (View source styles):

Base Classes [!toc]

.scroll-shadow - Root container element

Orientation Variants [!toc]

.scroll-shadow--vertical - Vertical scrolling (default)
.scroll-shadow--horizontal - Horizontal scrolling

State Modifiers [!toc]

.scroll-shadow--hide-scrollbar - Hides native scrollbar

CSS Variables

The ScrollShadow component uses CSS variables to size the fade mask and reserve space for visible native scrollbars:

Variable	Default	Description
`--scroll-shadow-size`	`40px`	Controls the fade gradient size. This is set from the `size` prop.
`--scroll-shadow-offset`	`0px`	How far the container must be scrolled before the fade starts. This is set from the `offset` prop.
`--scroll-shadow-scrollbar-size`	`10px` (`0px` when `hideScrollBar`)	Reserves a solid mask gutter for the native scrollbar so the fade does not cover it. Override for wider scrollbars.

Data Attributes

The component uses data attributes to control shadow visibility:

Scroll States: [data-top-scroll], [data-bottom-scroll], [data-left-scroll], [data-right-scroll] - Applied when content can be scrolled in that direction
Combined States: [data-top-bottom-scroll], [data-left-right-scroll] - Applied when content can be scrolled in both directions
Orientation: [data-orientation="vertical"] or [data-orientation="horizontal"] - Indicates scroll direction
Size: [data-scroll-shadow-size] - Contains the shadow gradient size value
Shadow Mode: [data-scroll-shadow-mode] - "auto" when the fade is derived from the scroll position, "manual" when visibility is controlled or isEnabled is false

Scroll-Driven Fade

In auto mode, browsers that support scroll-driven animations derive the fade from the scroll position in CSS. The mask is therefore correct on the very first paint, with no measurement and no flash of unfaded content during hydration. Browsers without support fall back to the [data-*-scroll] attributes above, which are written after hydration. Two things to keep in mind when customizing:

In auto mode the root always resolves a mask-image, even when there is nothing to scroll. That makes it a stacking context and a containing block for position: fixed descendants. Set visibility explicitly if you need to opt out.
The scroll-driven fade uses the animation property on the root. Applying an animate-* utility to the same element replaces it and leaves no fade. Animate a wrapper instead.

API Reference

ScrollShadow

Prop	Type	Default	Description
`orientation`	`"vertical"` \| `"horizontal"`	`"vertical"`	The scroll direction
`variant`	`"fade"`	`"fade"`	The visual shadow effect style
`size`	`number`	`40`	The shadow gradient size in pixels
`offset`	`number`	`0`	The scroll offset before showing shadows (in pixels)
`hideScrollBar`	`boolean`	`false`	Whether to hide the native scrollbar
`isEnabled`	`boolean`	`true`	Whether scroll shadow detection is enabled
`visibility`	`"auto"` \| `"both"` \| `"top"` \| `"bottom"` \| `"left"` \| `"right"` \| `"none"`	`"auto"`	Controlled shadow visibility state
`onVisibilityChange`	`(visibility: ScrollShadowVisibility) => void`	-	Callback invoked when shadow visibility changes
`className`	`string`	-	Additional CSS classes to apply to the root element
`children`	`ReactNode`	-	The scrollable content

ScrollShadow

Usage

Examples

Orientation

Shadow Size

With Card

Hide Scroll Bar

Visibility Change

Customization

Tailwind CSS

Global CSS

Styling Reference

CSS Classes

Base Classes [!toc]

Orientation Variants [!toc]

State Modifiers [!toc]

CSS Variables

Data Attributes

Scroll-Driven Fade

API Reference

ScrollShadow

Related Components