Configuration & Styling

interface ClassNames {
  /** Content element containing the scrollable content */
  contentEl: string;
  
  /** Wrapper element for the content with native scrollbar hidden */
  contentWrapper: string;
  
  /** Offset element for hiding native scrollbar */
  offset: string;
  
  /** Mask element for clipping content */
  mask: string;
  
  /** Main wrapper element containing all SimpleBar components */
  wrapper: string;
  
  /** Placeholder element for maintaining layout dimensions */
  placeholder: string;
  
  /** Custom scrollbar handle element */
  scrollbar: string;
  
  /** Track element containing the scrollbar */
  track: string;
  
  /** Height auto-observer wrapper for dynamic content sizing */
  heightAutoObserverWrapperEl: string;
  
  /** Height auto-observer element */
  heightAutoObserverEl: string;
  
  /** Class applied when scrollbar is visible */
  visible: string;
  
  /** Class applied to horizontal scrollbar components */
  horizontal: string;
  
  /** Class applied to vertical scrollbar components */
  vertical: string;
  
  /** Class applied when hovering over scrollbar */
  hover: string;
  
  /** Class applied when dragging scrollbar */
  dragging: string;
  
  /** Class applied when scrolling is active */
  scrolling: string;
  
  /** Class applied when element is scrollable */
  scrollable: string;
  
  /** Class applied when mouse enters scrollable area */
  mouseEntered: string;
}

import SimpleBar from "simplebar";

// Custom class names for theming
const simpleBar = new SimpleBar(element, {
  classNames: {
    scrollbar: 'my-custom-scrollbar',
    track: 'my-custom-track',
    visible: 'my-visible-state',
    hover: 'my-hover-state'
  }
});

/**
 * Default configuration options used when no custom options are provided
 */
static defaultOptions: {
  forceVisible: false,
  clickOnTrack: true,
  scrollbarMinSize: 25,
  scrollbarMaxSize: 0,
  ariaLabel: 'scrollable content',
  tabIndex: 0,
  classNames: ClassNames,
  scrollableNode: null,
  contentNode: null,
  autoHide: true
};

interface BehaviorOptions {
  /** Force scrollbar visibility regardless of content overflow */
  forceVisible?: boolean | 'x' | 'y';
  
  /** Enable clicking on track area to scroll */
  clickOnTrack?: boolean;
  
  /** Automatically hide scrollbar when not actively scrolling */
  autoHide?: boolean;
}

// Always show scrollbars
const simpleBar = new SimpleBar(element, {
  forceVisible: true,
  autoHide: false
});

// Show only vertical scrollbar, disable track clicking
const simpleBar = new SimpleBar(element, {
  forceVisible: 'y',
  clickOnTrack: false
});

interface SizingOptions {
  /** Minimum scrollbar handle size in pixels */
  scrollbarMinSize?: number;
  
  /** Maximum scrollbar handle size in pixels (0 = no limit) */
  scrollbarMaxSize?: number;
}

// Large minimum scrollbar for touch interfaces
const simpleBar = new SimpleBar(element, {
  scrollbarMinSize: 40,
  scrollbarMaxSize: 200
});

interface AccessibilityOptions {
  /** Aria label for screen readers */
  ariaLabel?: string;
  
  /** Tab index for keyboard navigation */
  tabIndex?: number;
}

// Custom accessibility configuration
const simpleBar = new SimpleBar(element, {
  ariaLabel: 'Chat message history',
  tabIndex: 1
});

interface AdvancedOptions {
  /** Custom element to use as scrollable container */
  scrollableNode?: HTMLElement | null;
  
  /** Custom element containing the actual content */
  contentNode?: HTMLElement | null;
}

// Use existing DOM structure
const scrollContainer = document.querySelector('.my-scroll-container');
const contentContainer = document.querySelector('.my-content');

const simpleBar = new SimpleBar(element, {
  scrollableNode: scrollContainer,
  contentNode: contentContainer
});

/* Scrollbar track */
.simplebar-track {
  background: #f0f0f0;
  border-radius: 3px;
}

/* Scrollbar handle */
.simplebar-scrollbar::before {
  background: #888;
  border-radius: 3px;
  opacity: 0.7;
}

/* Hover states */
.simplebar-scrollbar.simplebar-hover::before {
  background: #555;
  opacity: 1;
}

/* Dark theme scrollbar */
.dark-theme .simplebar-track {
  background: #2a2a2a;
}

.dark-theme .simplebar-scrollbar::before {
  background: #666;
}

.dark-theme .simplebar-scrollbar.simplebar-hover::before {
  background: #888;
}

/* Colored scrollbar */
.colored-scrollbar .simplebar-scrollbar::before {
  background: linear-gradient(to bottom, #4CAF50, #45a049);
}

/* Custom show/hide animation */
.simplebar-scrollbar {
  transition: opacity 0.3s ease-in-out;
}

/* Custom scrollbar width */
.simplebar-track.simplebar-vertical {
  width: 8px;
}

.simplebar-track.simplebar-horizontal {
  height: 8px;
}

/**
 * Detect native scrollbar width
 * Cached value that updates on window resize/device pixel ratio changes
 * @returns Width of native scrollbar in pixels
 */
function scrollbarWidth(): number;

<div dir="rtl" data-simplebar>
  <p>محتوى قابل للتمرير</p>
</div>

/* RTL-specific styling if needed */
[dir="rtl"] .simplebar-track.simplebar-vertical {
  left: 0;
  right: auto;
}

/**
 * Get RTL browser compatibility helpers
 * Tests browser behavior for RTL scrolling inconsistencies
 */
static getRtlHelpers(): {
  /** Determines if scrolling responds with negative values */
  isScrollOriginAtZero: boolean;
  /** Determines if origin scrollbar position is inverted */
  isScrollingToNegative: boolean;
} | null;