# Scroll Area

Augments native scroll functionality with custom, cross-browser styling.

Source: https://webjs.dev/ui/docs/components/scroll-area

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { scrollAreaClass } from '#components/ui/scroll-area.ts';
import { separatorClass } from '#components/ui/separator.ts';

const tags = Array.from({ length: 50 }).map(
  (_, i, a) => `v1.2.0-beta.${a.length - i}`,
);

export default function ScrollAreaDemo() {
  return html`
    <div data-slot="scroll-area" tabindex="0" role="region" aria-label="Tags" class=${cn(scrollAreaClass(), 'h-72 w-48 rounded-md border')}>
      <div class="p-4">
        <h4 class="mb-4 text-sm leading-none font-medium">Tags</h4>
        ${tags.map((tag) => html`
          <div class="text-sm">${tag}</div>
          <div role="none" data-slot="separator" data-orientation="horizontal" class=${cn(separatorClass(), 'my-2')}></div>
        `)}
      </div>
    </div>
  `;
}
```

## Installation

```bash
npx @webjsdev/ui add scroll-area
```

### Copy and paste the following code into your project.

````ts title="components/ui/scroll-area.ts"
/**
 * Scroll area: a region that scrolls inside a fixed size, with a thin,
 * theme-coloured scrollbar. Tier-1 class helper on native overflow; no
 * script, no custom scrollbar element.
 *
 * shadcn parity:
 *   ScrollArea (+ its viewport)  → scrollAreaClass({ orientation })
 *   ScrollBar                    → the native scrollbar, styled through
 *                                  scrollbar-width and scrollbar-color
 *
 * shadcn draws its own scrollbar with Radix. The platform's scrollbar is
 * styled instead here, which keeps native scrolling, momentum, keyboard
 * scrolling and the browser's own overlay behaviour intact. Give the element
 * a size (`h-72`, `max-h-96`, `w-96`) so it has something to scroll inside.
 *
 * A11y (required for accessible output): a region that scrolls must be
 * reachable by keyboard, so give it `tabindex="0"`, and because a focusable
 * region needs a name, add `role="region"` with an `aria-label` that says what
 * scrolls ("Release notes"). The focus ring is part of the class.
 *
 * Design tokens used: --border, --ring.
 *
 * @example
 * ```html
 * <div class=${cn(scrollAreaClass(), 'h-72 w-48 rounded-md border')} tabindex="0" role="region" aria-label="Tags">
 *   <ul class="p-4">${tags.map((t) => html`<li>${t}</li>`)}</ul>
 * </div>
 * ```
 */
import { cn } from '../lib/utils.ts';

const BASE =
  'relative rounded-[inherit] [scrollbar-width:thin] [scrollbar-color:var(--color-border)_transparent] outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50';

const ORIENTATIONS = {
  vertical: 'overflow-y-auto overflow-x-hidden',
  horizontal: 'overflow-x-auto overflow-y-hidden',
  both: 'overflow-auto',
} as const;

export type ScrollAreaOrientation = keyof typeof ORIENTATIONS;

/** The scrolling region. `orientation` picks the axis (default vertical). */
export function scrollAreaClass(opts: { orientation?: ScrollAreaOrientation } = {}): string {
  return cn(BASE, ORIENTATIONS[opts.orientation ?? 'vertical']);
}
````

### Update the import paths to match your project setup.

## Usage

```ts
import { scrollAreaClass } from '#components/ui/scroll-area.ts';
import { cn } from '#lib/utils/cn.ts';
```

```ts
<div
  tabindex="0"
  role="region"
  aria-label="Release notes"
  class=${cn(scrollAreaClass(), 'h-[200px] w-[350px] rounded-md border p-4')}
>
  Your scrollable content here.
</div>
```

## Composition

A scroll area is one element. The kit styles the browser's own scrollbar rather than drawing a `ScrollBar` part, so native scrolling, momentum and keyboard scrolling keep working:

```text
div (scrollAreaClass)
└── your content
```

## Horizontal

Use `scrollAreaClass({ orientation: 'horizontal' })` for horizontal scrolling.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { scrollAreaClass } from '#components/ui/scroll-area.ts';

export interface Artwork {
  artist: string;
  art: string;
}

export const works: Artwork[] = [
  {
    artist: 'Ornella Binni',
    art: 'https://images.unsplash.com/photo-1465869185982-5a1a7522cbcb?auto=format&fit=crop&w=300&q=80',
  },
  {
    artist: 'Tom Byrom',
    art: 'https://images.unsplash.com/photo-1548516173-3cabfa4607e9?auto=format&fit=crop&w=300&q=80',
  },
  {
    artist: 'Vladimir Malyavko',
    art: 'https://images.unsplash.com/photo-1494337480532-3725c85fd2ab?auto=format&fit=crop&w=300&q=80',
  },
];

export default function ScrollAreaHorizontalDemo() {
  return html`
    <div data-slot="scroll-area" tabindex="0" role="region" aria-label="Artwork" class=${cn(scrollAreaClass({ orientation: 'horizontal' }), 'w-96 rounded-md border whitespace-nowrap')}>
      <div class="flex w-max space-x-4 p-4">
        ${works.map((artwork) => html`
          <figure class="shrink-0">
            <div class="overflow-hidden rounded-md">
              <img
                src=${artwork.art}
                alt=${`Photo by ${artwork.artist}`}
                class="aspect-[3/4] h-fit w-fit object-cover"
                width="300"
                height="400"
              >
            </div>
            <figcaption class="pt-2 text-xs text-muted-foreground">
              Photo by
              <span class="font-semibold text-foreground">${artwork.artist}</span>
            </figcaption>
          </figure>
        `)}
      </div>
    </div>
  `;
}
```

## RTL

To enable RTL support, see the [RTL configuration guide](https://webjs.dev/ui/docs/rtl).

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { scrollAreaClass } from '#components/ui/scroll-area.ts';
import { separatorClass } from '#components/ui/separator.ts';

const tags = Array.from({ length: 50 }).map(
  (_, i, a) => `v1.2.0-beta.${a.length - i}`,
);

const translations = {
  en: {
    dir: 'ltr',
    values: {
      tags: 'Tags',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      tags: 'العلامات',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      tags: 'תגיות',
    },
  },
};

export default function ScrollAreaRtl() {
  const lang = 'ar';
  const { dir, values: t } = translations[lang];

  return html`
    <div data-slot="scroll-area" tabindex="0" role="region" aria-label=${t.tags} dir=${dir} lang=${lang} class=${cn(scrollAreaClass(), 'h-72 w-48 rounded-md border')}>
      <div class="p-4">
        <h4 class="mb-4 text-sm leading-none font-medium">${t.tags}</h4>
        ${tags.map((tag) => html`
          <div class="text-sm">${tag}</div>
          <div role="none" data-slot="separator" data-orientation="horizontal" class=${cn(separatorClass(), 'my-2')}></div>
        `)}
      </div>
    </div>
  `;
}
```

## API Reference

### scrollAreaClass

`scrollAreaClass()` returns the classes for the scrolling region: native overflow on the chosen axis, a thin scrollbar in the theme's border colour, and a focus ring. Give the element a size so it has something to scroll inside, and `tabindex="0"`, `role="region"` and an `aria-label` so a keyboard can reach it and a screen reader can name it.

| Option | Type | Default |
| --- | --- | --- |
| `orientation` | `"vertical" \| "horizontal" \| "both"` | `"vertical"` |
