Skip to content

Custom Scrollbar ​

The Custom Scrollbar utility in the Phenix Design System allows you to apply styled scrollbars to elements with overflow, replacing the browser's default scrollbar appearance for better visual integration.

Overview ​

Browsers' default scrollbars can vary in appearance and often don't match a website's design aesthetic. The custom scrollbar utility provides a consistent, minimal, and themeable scrollbar style.

Usage ​

Apply the .px-scrollbar class to any element that has overflow: auto or overflow: scroll (or overflow-y: auto/scroll, overflow-x: auto/scroll).

html
<!-- Container with vertical overflow and custom scrollbar -->
<div class="px-scrollbar" style="height: 200px; overflow-y: auto;">
  <p>This content is long enough to cause vertical scrolling.</p>
  <p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>
  <!-- More content... -->
</div>

<!-- Container with horizontal overflow and custom scrollbar -->
<div class="px-scrollbar" style="width: 300px; overflow-x: auto; white-space: nowrap;">
  This text is very long and will cause horizontal scrolling. Lorem ipsum dolor sit amet...
</div>

How It Works ​

The .px-scrollbar class uses vendor-prefixed CSS properties (::-webkit-scrollbar, ::-webkit-scrollbar-track, ::-webkit-scrollbar-thumb) to style the scrollbar components in WebKit-based browsers (like Chrome, Safari, Edge). It typically creates a thinner track and thumb compared to default scrollbars.

Note: Styling scrollbars using these properties is not universally supported across all browsers (e.g., Firefox uses different properties like scrollbar-width and scrollbar-color, which might also be targeted by the utility for broader compatibility).

Customization ​

The appearance of the custom scrollbar can be controlled using CSS variables:

  • --scrollbar-color: Controls the color of the scrollbar track (the background area). Default is typically a light gray or transparent.
  • --scrollbar-thumb: Controls the color of the scrollbar thumb (the draggable part). Default is typically a darker gray.
html
<!-- Custom scrollbar colors -->
<div class="px-scrollbar" 
     style="height: 150px; overflow-y: auto; --scrollbar-color: var(--primary-offwhite); --scrollbar-thumb: var(--primary-color);">
  <!-- Content -->
</div>

Use Cases ​

  • Styling scrollable <div> containers.
  • Customizing the scrollbar for <textarea> elements.
  • Improving the look of scrollable sidebars, modals, or dropdowns.

Best Practices ​

  1. Ensure Visibility: Make sure the scrollbar thumb has sufficient contrast against the track for usability.
  2. Don't Make it Too Thin: While aiming for a minimal look, ensure the scrollbar remains easily grabbable with a mouse.
  3. Test Cross-Browser: Check the appearance in different browsers, as support and rendering can vary.
  4. Consider Touch Devices: Custom scrollbars are primarily for desktop browsers; touch devices typically have overlay scrollbars that are less intrusive.

Released under the MIT License.