ScrollArea Component

Overview

The ScrollArea component provides a customizable scrollable area with smooth scrolling and custom scrollbars. It's designed for content that exceeds the available space and needs to be scrollable. Built on top of @dashflowx/core components.

Quick Start

Installation

npm install @dashflowx/core

Basic Implementation

import { ScrollArea } from '@/components/scrollarea'

export default function MyComponent() {
  return (
    <ScrollArea 
      height="h-80" 
      width="w-64"
      type="basic"
    />
  )
}

With Custom Content

import { ScrollArea } from '@/components/scrollarea'

export default function CustomScrollArea() {
  return (
    <ScrollArea height="h-72" width="w-48">
      <div className="p-4 space-y-4">
        <h3 className="text-lg font-semibold">Custom Content</h3>
        {Array.from({ length: 20 }, (_, i) => (
          <div key={i} className="p-3 bg-gray-50 rounded">
            Item {i + 1}
          </div>
        ))}
      </div>
    </ScrollArea>
  )
}

Props

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes
`height`	`string`	`'h-72'`	Height of the scroll area
`width`	`string`	`'w-48'`	Width of the scroll area
`type`	`'basic' \| 'tags' \| 'messages' \| 'files' \| 'table'`	`'basic'`	Type of content to display
`children`	`React.ReactNode`	-	Custom content to display
`orientation`	`'vertical' \| 'horizontal' \| 'both'`	`'vertical'`	Scroll orientation
`scrollbarSize`	`'sm' \| 'md' \| 'lg'`	`'md'`	Size of the scrollbar
`showScrollbar`	`boolean`	`true`	Whether to show scrollbar
`autoHide`	`boolean`	`true`	Auto-hide scrollbar on hover
`scrollBehavior`	`'smooth' \| 'auto'`	`'smooth'`	Scroll behavior

Content Types

Basic Content

import { ScrollArea } from '@/components/scrollarea'

export default function BasicScrollArea() {
  return (
    <ScrollArea type="basic" />
  )
}

Preview:

Scrollable Content

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Item 9

Item 10

Item 11

Item 12

Item 13

Item 14

Item 15

Item 16

Item 17

Item 18

Item 19

Item 20

Tags Content

import { ScrollArea } from '@/components/scrollarea'

export default function TagsScrollArea() {
  return (
    <ScrollArea type="tags" />
  )
}

Preview:

Chat Messages

import { ScrollArea } from '@/components/scrollarea'

export default function MessagesScrollArea() {
  return (
    <ScrollArea type="messages" />
  )
}

Preview:

Chat Messages

User

This is message 1 with some content that might wrap to multiple lines.

Bot

This is message 2 with some content that might wrap to multiple lines.

User

This is message 3 with some content that might wrap to multiple lines.

Bot

This is message 4 with some content that might wrap to multiple lines.

User

This is message 5 with some content that might wrap to multiple lines.

Bot

This is message 6 with some content that might wrap to multiple lines.

User

This is message 7 with some content that might wrap to multiple lines.

Bot

This is message 8 with some content that might wrap to multiple lines.

User

This is message 9 with some content that might wrap to multiple lines.

Bot

This is message 10 with some content that might wrap to multiple lines.

User

This is message 11 with some content that might wrap to multiple lines.

Bot

This is message 12 with some content that might wrap to multiple lines.

User

This is message 13 with some content that might wrap to multiple lines.

Bot

This is message 14 with some content that might wrap to multiple lines.

User

This is message 15 with some content that might wrap to multiple lines.

Bot

This is message 16 with some content that might wrap to multiple lines.

User

This is message 17 with some content that might wrap to multiple lines.

Bot

This is message 18 with some content that might wrap to multiple lines.

User

This is message 19 with some content that might wrap to multiple lines.

Bot

This is message 20 with some content that might wrap to multiple lines.

File List

import { ScrollArea } from '@/components/scrollarea'

export default function FilesScrollArea() {
  return (
    <ScrollArea type="files" />
  )
}

Preview:

Files

file-1.txt

50 KB

file-2.txt

100 KB

file-3.txt

150 KB

file-4.txt

200 KB

file-5.txt

250 KB

file-6.txt

300 KB

file-7.txt

350 KB

file-8.txt

400 KB

file-9.txt

450 KB

file-10.txt

500 KB

file-11.txt

550 KB

file-12.txt

600 KB

file-13.txt

650 KB

file-14.txt

700 KB

file-15.txt

750 KB

Data Table

import { ScrollArea } from '@/components/scrollarea'

export default function TableScrollArea() {
  return (
    <ScrollArea type="table" />
  )
}

Preview:

Data Table

ID	Name	Value	Status
1	Item 1	10	Active
2	Item 2	20	Inactive
3	Item 3	30	Pending
4	Item 4	40	Active
5	Item 5	50	Inactive
6	Item 6	60	Pending
7	Item 7	70	Active
8	Item 8	80	Inactive
9	Item 9	90	Pending
10	Item 10	100	Active
11	Item 11	110	Inactive
12	Item 12	120	Pending
13	Item 13	130	Active
14	Item 14	140	Inactive
15	Item 15	150	Pending
16	Item 16	160	Active
17	Item 17	170	Inactive
18	Item 18	180	Pending
19	Item 19	190	Active
20	Item 20	200	Inactive
21	Item 21	210	Pending
22	Item 22	220	Active
23	Item 23	230	Inactive
24	Item 24	240	Pending
25	Item 25	250	Active

Size Variations

Small Scroll Area

import { ScrollArea } from '@/components/scrollarea'

export default function SmallScrollArea() {
  return (
    <ScrollArea height="h-32" width="w-40" />
  )
}

Preview:

Scrollable Content

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Item 9

Item 10

Item 11

Item 12

Item 13

Item 14

Item 15

Item 16

Item 17

Item 18

Item 19

Item 20

Large Scroll Area

import { ScrollArea } from '@/components/scrollarea'

export default function LargeScrollArea() {
  return (
    <ScrollArea height="h-96" width="w-64" />
  )
}

Preview:

Scrollable Content

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Item 9

Item 10

Item 11

Item 12

Item 13

Item 14

Item 15

Item 16

Item 17

Item 18

Item 19

Item 20

Custom Styled Scroll Area

import { ScrollArea } from '@/components/scrollarea'

export default function CustomStyledScrollArea() {
  return (
    <ScrollArea 
      className="border border-blue-500 rounded-lg" 
      height="h-80"
      width="w-56"
    />
  )
}

Preview:

Scrollable Content

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Item 9

Item 10

Item 11

Item 12

Item 13

Item 14

Item 15

Item 16

Item 17

Item 18

Item 19

Item 20

Custom Content

import { ScrollArea } from '@/components/scrollarea'

export default function CustomContentScrollArea() {
  return (
    <ScrollArea height="h-72" width="w-48">
      <div className="p-4">
        <h4 className="mb-4 text-sm font-medium">Custom Content</h4>
        <div className="space-y-2">
          <div className="p-2 bg-blue-50 rounded">Custom item 1</div>
          <div className="p-2 bg-green-50 rounded">Custom item 2</div>
          <div className="p-2 bg-purple-50 rounded">Custom item 3</div>
          {/* More items... */}
        </div>
      </div>
    </ScrollArea>
  )
}

Preview:

Scrollable Content

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Item 9

Item 10

Item 11

Item 12

Item 13

Item 14

Item 15

Item 16

Item 17

Item 18

Item 19

Item 20

Advanced Features

Scrollbar Customization

import { ScrollArea } from '@/components/scrollarea'

export default function CustomScrollbarScrollArea() {
  return (
    <ScrollArea 
      scrollbarSize="lg"
      autoHide={false}
      showScrollbar={true}
    />
  )
}

Preview:

Scrollable Content

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Item 9

Item 10

Item 11

Item 12

Item 13

Item 14

Item 15

Item 16

Item 17

Item 18

Item 19

Item 20

Horizontal Scrolling

import { ScrollArea } from '@/components/scrollarea'

export default function HorizontalScrollArea() {
  return (
    <ScrollArea 
      orientation="horizontal"
      height="h-32"
      width="w-96"
    />
  )
}

Preview:

Scrollable Content

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Item 9

Item 10

Item 11

Item 12

Item 13

Item 14

Item 15

Item 16

Item 17

Item 18

Item 19

Item 20

Both Directions Scrolling

import { ScrollArea } from '@/components/scrollarea'

export default function BothDirectionsScrollArea() {
  return (
    <ScrollArea 
      orientation="both"
      height="h-64"
      width="w-80"
    />
  )
}

Preview:

Scrollable Content

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Item 9

Item 10

Item 11

Item 12

Item 13

Item 14

Item 15

Item 16

Item 17

Item 18

Item 19

Item 20

Auto-Hide Scrollbar

import { ScrollArea } from '@/components/scrollarea'

export default function AutoHideScrollArea() {
  return (
    <ScrollArea 
      autoHide={true}
      scrollBehavior="smooth"
    />
  )
}

Preview:

Scrollable Content

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Item 9

Item 10

Item 11

Item 12

Item 13

Item 14

Item 15

Item 16

Item 17

Item 18

Item 19

Item 20

Real-World Examples

Chat Application

import { ScrollArea } from '@/components/scrollarea'

export default function ChatApp() {
  const messages = [
    { id: 1, user: 'Alice', message: 'Hello everyone!' },
    { id: 2, user: 'Bob', message: 'Hi Alice, how are you?' },
    { id: 3, user: 'Charlie', message: 'Good morning!' },
    // ... more messages
  ];

  return (
    <div className="flex flex-col h-96">
      <div className="p-4 border-b">
        <h2 className="text-lg font-semibold">Team Chat</h2>
      </div>
      <ScrollArea 
        type="messages"
        height="h-full"
        width="w-full"
        className="flex-1"
      />
      <div className="p-4 border-t">
        <input 
          type="text" 
          placeholder="Type a message..."
          className="w-full p-2 border rounded"
        />
      </div>
    </div>
  )
}

File Explorer

import { ScrollArea } from '@/components/scrollarea'

export default function FileExplorer() {
  return (
    <div className="w-80 h-96 border rounded-lg">
      <div className="p-3 border-b bg-gray-50">
        <h3 className="font-medium">Files</h3>
      </div>
      <ScrollArea 
        type="files"
        height="h-full"
        width="w-full"
        scrollbarSize="sm"
        autoHide={true}
      />
    </div>
  )
}

Data Dashboard

import { ScrollArea } from '@/components/scrollarea'

export default function DataDashboard() {
  return (
    <div className="grid grid-cols-2 gap-4">
      <div className="border rounded-lg">
        <div className="p-4 border-b">
          <h3 className="font-semibold">Recent Activity</h3>
        </div>
        <ScrollArea 
          type="basic"
          height="h-64"
          width="w-full"
        />
      </div>
      
      <div className="border rounded-lg">
        <div className="p-4 border-b">
          <h3 className="font-semibold">Data Table</h3>
        </div>
        <ScrollArea 
          type="table"
          height="h-64"
          width="w-full"
          orientation="both"
        />
      </div>
    </div>
  )
}

import { ScrollArea } from '@/components/scrollarea'

export default function CodeEditorSidebar() {
  const files = [
    'src/components/Button.tsx',
    'src/components/Input.tsx',
    'src/components/Modal.tsx',
    'src/utils/helpers.ts',
    'src/types/index.ts',
    // ... more files
  ];

  return (
    <div className="w-64 h-full bg-gray-900 text-white">
      <div className="p-3 border-b border-gray-700">
        <h3 className="text-sm font-medium">Explorer</h3>
      </div>
      <ScrollArea 
        height="h-full"
        width="w-full"
        className="bg-gray-900"
        scrollbarSize="sm"
      >
        <div className="p-2">
          {files.map((file, index) => (
            <div 
              key={index}
              className="px-2 py-1 text-sm hover:bg-gray-800 rounded cursor-pointer"
            >
              📄 {file}
            </div>
          ))}
        </div>
      </ScrollArea>
    </div>
  )
}

Mobile-Friendly List

import { ScrollArea } from '@/components/scrollarea'

export default function MobileList() {
  return (
    <div className="max-w-sm mx-auto">
      <ScrollArea 
        type="basic"
        height="h-96"
        width="w-full"
        scrollBehavior="smooth"
        scrollbarSize="sm"
        className="border rounded-lg"
      />
    </div>
  )
}

Common Use Cases

Long Content Lists

import { ScrollArea } from '@/components/scrollarea'

const longContentList = (
  <ScrollArea type="basic" height="h-80" />
);

Chat Messages

import { ScrollArea } from '@/components/scrollarea'

const chatMessages = (
  <ScrollArea type="messages" height="h-96" />
);

File Lists

import { ScrollArea } from '@/components/scrollarea'

const fileList = (
  <ScrollArea type="files" height="h-72" />
);

Data Tables

import { ScrollArea } from '@/components/scrollarea'

const dataTable = (
  <ScrollArea type="table" height="h-80" />
);

Best Practices

Appropriate Height

Set appropriate height for scroll areas.

// ✅ Good - Appropriate height
<ScrollArea height="h-72" />

// ❌ Avoid - Too tall or too short
<ScrollArea height="h-screen" />

Consistent Styling

Maintain consistent styling across scroll areas.

// ✅ Good - Consistent styling
<ScrollArea className="border border-gray-300 rounded-lg" />

// ❌ Avoid - Inconsistent styling
<ScrollArea className="random-styles" />

Choose Right Content Type

Use appropriate content types for different use cases.

// ✅ Good - Use specific types
<ScrollArea type="messages" />
<ScrollArea type="files" />
<ScrollArea type="table" />

// ❌ Avoid - Always using basic
<ScrollArea type="basic" />

Custom Content

Provide custom content when needed.

// ✅ Good - Custom content
<ScrollArea>
  <div className="p-4">
    <h4>Custom Title</h4>
    <div>Your custom content here</div>
  </div>
</ScrollArea>

// ❌ Avoid - Empty scroll areas
<ScrollArea />

Responsive Design

Make scroll areas responsive.

// ✅ Good - Responsive sizing
<ScrollArea height="h-72 md:h-96" width="w-full md:w-64" />

// ❌ Avoid - Fixed sizes only
<ScrollArea height="h-72" width="w-48" />

Customization

Custom Styling

You can customize the scroll area appearance using CSS classes:

<ScrollArea 
  className="border border-gray-300 rounded-lg shadow-lg" 
  height="h-80"
  width="w-56"
/>

Different Themes

Use different themes for different contexts:

// Light theme
<ScrollArea 
  className="bg-white border-gray-200" 
  height="h-72"
  width="w-48"
/>

// Dark theme
<ScrollArea 
  className="bg-gray-900 border-gray-700 text-white" 
  height="h-72"
  width="w-48"
/>

// Brand theme
<ScrollArea 
  className="bg-blue-50 border-blue-200" 
  height="h-72"
  width="w-48"
/>

Size Variations

Use different sizes for different emphasis levels:

// Small scroll area
<ScrollArea height="h-32" width="w-40" />

// Standard scroll area
<ScrollArea height="h-72" width="w-48" />

// Large scroll area
<ScrollArea height="h-96" width="w-64" />

Advanced Usage

Dynamic Content

Load content dynamically:

import { ScrollArea } from '@/components/scrollarea'
import { useState, useEffect } from 'react'

export default function DynamicScrollArea() {
  const [content, setContent] = useState([]);

  useEffect(() => {
    // Load content from API
    loadContent().then(setContent);
  }, []);

  return (
    <ScrollArea height="h-80" width="w-64">
      <div className="p-4">
        <h4 className="mb-4 text-sm font-medium">Dynamic Content</h4>
        {content.map((item, index) => (
          <div key={index} className="text-sm py-2 border-b border-gray-200 last:border-b-0">
            {item}
          </div>
        ))}
      </div>
    </ScrollArea>
  );
}

Custom Scrollbar Styling

Customize scrollbar appearance:

import { ScrollArea, ScrollBar } from '@/components/scrollarea'

export default function CustomScrollbarScrollArea() {
  return (
    <ScrollArea 
      height="h-72" 
      width="w-48"
      className="border border-gray-300 rounded-lg"
    >
      <div className="p-4">
        <h4 className="mb-4 text-sm font-medium">Custom Scrollbar</h4>
        {/* Content */}
      </div>
      <ScrollBar className="bg-gray-200" />
    </ScrollArea>
  );
}

Scroll Position Management

Handle scroll position:

import { ScrollArea } from '@/components/scrollarea'
import { useRef } from 'react'

export default function ScrollPositionScrollArea() {
  const scrollAreaRef = useRef(null);
  const [scrollPosition, setScrollPosition] = useState(0);

  const handleScroll = (position) => {
    setScrollPosition(position);
    // Save scroll position to localStorage
    localStorage.setItem('scrollPosition', position);
  };

  return (
    <ScrollArea 
      ref={scrollAreaRef}
      height="h-72" 
      width="w-48"
      onScroll={handleScroll}
    >
      <div className="p-4">
        <h4 className="mb-4 text-sm font-medium">Scroll Position: {scrollPosition}</h4>
        {/* Content */}
      </div>
    </ScrollArea>
  );
}

Troubleshooting

Common Issues

ScrollArea Not Showing Content

Problem: Content is not visible or scrollable.

Solutions:

// ✅ Ensure proper height is set
<ScrollArea height="h-72" width="w-48">
  <div>Your content here</div>
</ScrollArea>

// ❌ Avoid - No height specified
<ScrollArea>
  <div>Your content here</div>
</ScrollArea>

Scrollbar Not Appearing

Problem: Scrollbar is not visible.

Solutions:

// ✅ Show scrollbar explicitly
<ScrollArea showScrollbar={true} />

// ✅ Disable auto-hide for debugging
<ScrollArea autoHide={false} />

// ✅ Use larger scrollbar
<ScrollArea scrollbarSize="lg" />

Performance Issues

Problem: Slow scrolling or rendering.

Solutions:

// ✅ Use appropriate content types
<ScrollArea type="basic" /> // For simple lists
<ScrollArea type="messages" /> // For chat messages
<ScrollArea type="files" /> // For file lists

// ✅ Limit content amount
<ScrollArea>
  {items.slice(0, 100).map(item => <div key={item.id}>{item.name}</div>)}
</ScrollArea>

Mobile Touch Issues

Problem: Touch scrolling not working properly.

Solutions:

// ✅ Use smooth scroll behavior
<ScrollArea scrollBehavior="smooth" />

// ✅ Ensure proper sizing
<ScrollArea height="h-96" width="w-full" />

Debugging Tips

Check Console: Look for error messages in browser console
Verify Props: Ensure all required props are provided
Test Content: Try with simple content first
Check CSS: Verify Tailwind classes are applied correctly

Browser Compatibility

Feature	Chrome	Firefox	Safari	Edge
Basic Scrolling	✅	✅	✅	✅
Custom Scrollbar	✅	✅	✅	✅
Smooth Scrolling	✅	✅	✅	✅
Touch Support	✅	✅	✅	✅

FAQ

Q: How do I make the ScrollArea responsive?

A: Use responsive Tailwind classes for height and width:

<ScrollArea 
  height="h-64 md:h-80 lg:h-96" 
  width="w-full md:w-64 lg:w-80" 
/>

Q: Can I customize the scrollbar appearance?

A: Yes, use the scrollbarSize prop and custom CSS:

<ScrollArea 
  scrollbarSize="lg"
  className="[&::-webkit-scrollbar]:w-4 [&::-webkit-scrollbar-track]:bg-gray-100"
/>

Q: How do I handle dynamic content?

A: Use the children prop with state management:

const [items, setItems] = useState([]);

<ScrollArea>
  {items.map(item => <div key={item.id}>{item.name}</div>)}
</ScrollArea>

Q: Is ScrollArea accessible?

A: Yes, it includes proper ARIA attributes and keyboard navigation support.

Q: Can I use ScrollArea in a mobile app?

A: Yes, it supports touch scrolling and is mobile-friendly.

Q: How do I prevent scrollbar from hiding?

A: Set autoHide={false}:

<ScrollArea autoHide={false} />

Q: Can I have both horizontal and vertical scrolling?

A: Yes, use orientation="both":

<ScrollArea orientation="both" />

List: For list content
Table: For tabular data
Card: For content containers
Panel: For panel content
Container: For content containers

API Reference

For the complete API reference and advanced usage patterns, see the ScrollArea API documentation.

Overview

Quick Start

Installation

Basic Implementation

With Custom Content

Props

Content Types

Basic Content

Scrollable Content

Tags Content

Tags

Chat Messages

Chat Messages

File List

Files

Data Table

Data Table

Size Variations

Small Scroll Area

Scrollable Content

Large Scroll Area

Scrollable Content

Custom Styled Scroll Area

Scrollable Content

Custom Content

Scrollable Content

Advanced Features

Scrollbar Customization

Scrollable Content

Horizontal Scrolling

Scrollable Content

Both Directions Scrolling

Scrollable Content

Auto-Hide Scrollbar

Scrollable Content

Real-World Examples

Chat Application

File Explorer

Data Dashboard

Code Editor Sidebar

Mobile-Friendly List

Common Use Cases

Long Content Lists

Chat Messages

File Lists

Data Tables

Best Practices

Appropriate Height

Consistent Styling

Choose Right Content Type

Custom Content

Responsive Design

Customization

Custom Styling

Different Themes

Size Variations

Advanced Usage

Dynamic Content

Custom Scrollbar Styling

Scroll Position Management

Troubleshooting

Common Issues

ScrollArea Not Showing Content

Scrollbar Not Appearing

Performance Issues

Mobile Touch Issues

Debugging Tips

Browser Compatibility

FAQ

Q: How do I make the ScrollArea responsive?

Q: Can I customize the scrollbar appearance?

Q: How do I handle dynamic content?

Q: Is ScrollArea accessible?

Q: Can I use ScrollArea in a mobile app?

Q: How do I prevent scrollbar from hiding?

Q: Can I have both horizontal and vertical scrolling?

Related Components

API Reference