Tailwind CSS Scrollbar

Basic example

Scrollbar is initialized automatically when you add data-te-perfect-scrollbar-init attribute to your container.

HTML
javascript

        
            
      <div
        data-te-perfect-scrollbar-init
        class="relative h-[400px] w-[600px] overflow-hidden">
        <img
          src="https://tecdn.b-cdn.net/img/new/slides/041.webp"
          alt="Wild Landscape"
          class="h-[700px] w-[1000px] max-w-none" />
      </div>

        
            
      // Initialization for ES Users
      import {
        PerfectScrollbar,
        initTE,
      } from "tw-elements";
      
      initTE({ PerfectScrollbar });

Hey there 👋 we want to make TW elements a community-driven project. It's open source and free, and we would like it to stay that way. If you enjoy it, help the project grow by sharing it with your peers. Every share counts, thank you!

Share via Reddit Share via StumbleUpon

Options

JavaScript init

You can easily init scrollbar with JavaScript. You have to invoke PerfectScrollbar() or te.PerfectScrollbar() if you are using UMD format and include options within that.

HTML
javascript
umd

ES UMD

        
            
      <div id="init-by-js" class="relative h-[400px] w-[600px] overflow-hidden">
        <img
          src="https://tecdn.b-cdn.net/img/new/slides/041.webp"
          alt="Wild Landscape"
          class="h-[700px] w-[1000px] max-w-none" />
      </div>

        
            
      import { PerfectScrollbar } from "tw-elements";
      
      const initByJS = document.querySelector("#init-by-js");
      const psInitbyJS = new PerfectScrollbar(initByJS);

        
            
      const initByJS = document.querySelector("#init-by-js");
      const psInitbyJS = new te.PerfectScrollbar(initByJS);

Data attributes

You can easily init scrollbar with options with data-te-attributes. You have to add data-te-perfect-scrollbar-init to your wrapper. If you want add options with data-te-attr you have to add for example data-te-suppress-scroll-x="true" to your container.

HTML
javascript

        
            
      <div
        data-te-perfect-scrollbar-init
        data-te-suppress-scroll-x="true"
        class="relative h-[400px] w-[600px] overflow-hidden">
        <img
          src="https://tecdn.b-cdn.net/img/new/slides/041.webp"
          alt="..."
          class="h-[700px] w-[1000px] max-w-none" />
      </div>

        
            
      // Initialization for ES Users
      import {
        PerfectScrollbar,
        initTE,
      } from "tw-elements";
      
      initTE({ PerfectScrollbar });

Colors example

Scrollbar's thumb and rail's colors can be customized by changing the default classes we add to them. Change the classes of the Scrollbar element that you would like to edit: railXColors, railXThumbColors, railYColors or railYThumbColors. Visit the API section to see the default classes for those elements.

HTML
javascript
umd

ES UMD

        
            
      <div
        id="scroll-colors"
        class="relative h-[400px] w-[600px] overflow-hidden">
        <img
          src="https://tecdn.b-cdn.net/img/new/slides/041.webp"
          alt="..."
          class="h-[700px] w-[1000px] max-w-none" />
      </div>

        
            
      import { PerfectScrollbar } from "tw-elements";
      
      const scrollColors = document.querySelector("#scroll-colors");
      const initScrollColors = new PerfectScrollbar(
        scrollColors,
        {},
        {
          railXColors:
            "group-[&.ps--active-x]/ps:!bg-[#90ee90] hover:!bg-[#eee] focus:!bg-[#eee] [&.ps--clicking]:!bg-[#eee]",
          railXThumbColors:
            "!bg-[#006400] group-hover/x:bg-[#999] group-focus/x:bg-[#999] group-[&.ps--clicking]/x:bg-[#999]",
          railYColors:
            "group-[&.ps--active-y]/ps:!bg-[#90ee90] hover:!bg-[#eee] focus:!bg-[#eee] [&.ps--clicking]:!bg-[#eee]",
          railYThumbColors:
            "!bg-[#006400] group-hover/y:bg-[#999] group-focus/y:bg-[#999] group-[&.ps--clicking]/y:bg-[#999]",
        }
      );

        
            
      const scrollColors = document.querySelector("#scroll-colors");
      const initScrollColors = new te.PerfectScrollbar(
        scrollColors,
        {},
        {
          railXColors:
            "group-[&.ps--active-x]/ps:!bg-[#90ee90] hover:!bg-[#eee] focus:!bg-[#eee] [&.ps--clicking]:!bg-[#eee]",
          railXThumbColors:
            "!bg-[#006400] group-hover/x:bg-[#999] group-focus/x:bg-[#999] group-[&.ps--clicking]/x:bg-[#999]",
          railYColors:
            "group-[&.ps--active-y]/ps:!bg-[#90ee90] hover:!bg-[#eee] focus:!bg-[#eee] [&.ps--clicking]:!bg-[#eee]",
          railYThumbColors:
            "!bg-[#006400] group-hover/y:bg-[#999] group-focus/y:bg-[#999] group-[&.ps--clicking]/y:bg-[#999]",
        }
      );

Events

PerfectScrollbar dispatches custom events.

ScrollX
ScrollY
ScrollUp
ScrollDown
ScrollLeft
ScrollRight
ScrollXEnd
ScrollYEnd
ScrollXStart
ScrollYStart

Example

HTML
javascript
umd

ES UMD

        
            
      <div id="scroll-x" class="relative h-[400px] w-[600px] overflow-hidden">
        <img
          src="https://tecdn.b-cdn.net/img/new/slides/041.webp"
          alt="Wild Landscape"
          class="h-[700px] w-[1000px] max-w-none" />
      </div>

        
            
      import { PerfectScrollbar } from "tw-elements";
      
      const scrollX = document.querySelector("#scroll-x");
      const initscrollX = new PerfectScrollbar(scrollX);
    
      scrollX.addEventListener('scrollX.te.ps', (e) => {
        // do something...
      });

        
            
      const scrollX = document.querySelector("#scroll-x");
      const initscrollX = new te.PerfectScrollbar(scrollX);

      scrollX.addEventListener('scrollX.te.ps', (e) => {
        // do something...
      });

Perfect Scrollbar

Import

Importing components depends on how your application works. If you intend to use the TW elements ES format, you must first import the component and then initialize it with the initTE method. If you are going to use the UMD format, just import the tw-elements package.

javascript
umd

ES UMD

        
            
        import { PerfectScrollbar, initTE } from "tw-elements";
        initTE({ PerfectScrollbar });

        
            
        import "tw-elements";

Usage

Via data attributes

Add the data-te-perfect-scrollbar-init attribute to the clickable element to apply the ripple effect. For ES format, you must first import and call the initTE method.

HTML

        
            
        <div
          data-te-perfect-scrollbar-init
          class="relative h-[400px] w-[600px] overflow-hidden">
          <img
            src="https://tecdn.b-cdn.net/img/new/slides/041.webp"
            alt="Wild Landscape"
            class="h-[700px] w-[1000px] max-w-none" />
        </div>

Via JavaScript

javascript
umd

ES UMD

        
            
        const initByJS = document.querySelector("#init-by-js");
        const psInitbyJS = new PerfectScrollbar(initByJS);

        
            
        const initByJS = document.querySelector("#init-by-js");
        const psInitbyJS = new te.PerfectScrollbar(initByJS);

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-te-, as in data-te-wheel-speed="2".

Name	Type	Default	Description
`handlers`	String[]	`['click-rail', 'drag-thumb', 'keyboard', 'wheel', 'touch']`	It is a list of handlers to scroll the element.
`wheelSpeed`	Number	`1`	The scroll speed applied to mousewheel event.
`wheelPropagation`	Boolean	`true`	If this option is true, when the scroll reaches the end of the side, mousewheel event will be propagated to parent element.
`swipeEasing`	Boolean	`true`	If this option is true, swipe scrolling will be eased.
`minScrollbarLength`	Number \| null	`null`	When set to an integer value, the thumb part of the scrollbar will not shrink below that number of pixels.
`maxScrollbarLength`	Number \| null	`null`	When set to an integer value, the thumb part of the scrollbar will not expand over that number of pixels.
`scrollingThreshold`	Number	`1000`	This sets threshold for ps--scrolling-x and ps--scrolling-y classes to remain. In the default CSS, they make scrollbars shown regardless of hover state. The unit is millisecond.
`suppressScrollX`	Boolean	`false`	When set to true, the scrollbar in X-axis will not be available, regardless of the content width.
`suppressScrollY`	Boolean	`false`	When set to true, the scroll bar in Y-axis will not be available, regardless of the content height.
`scrollXMarginOffset`	Number	`0`	The number of pixels the content width can surpass the container width without enabling the X-axis scroll bar. Allows some "wiggle room" or "offset break", so that X-axis scroll bar is not enabled just because of a few pixels.
`scrollYMarginOffset`	Number	`0`	The number of pixels the content width can surpass the container width without enabling the Y-axis scroll bar. Allows some "wiggle room" or "offset break", so that Y-axis scroll bar is not enabled just because of a few pixels.
`positionRight`	Boolean	`true`	Changes the sides of scrollbar rails

Classes

Custom classes can be passed via data attributes or JavaScript. For data attributes, append the class name to data-te-class, as in data-te-class-ps="".

Name	Default	Description
`ps`	group/ps overflow-hidden [overflow-anchor:none] touch-none	Sets styles for perfect scrollbar wrapper.
`railX`	group/x absolute bottom-0 h-[0.9375rem] hidden opacity-0 transition-[background-color,_opacity] duration-200 ease-linear motion-reduce:transition-none z-[1035] group-[&.ps--active-x]/ps:block group-hover/ps:opacity-60 group-focus/ps:opacity-60 group-[&.ps--scrolling-x]/ps:opacity-60 hover:!opacity-90 focus:!opacity-90 [&.ps--clicking]:!opacity-90 outline-none	Adds styles for horizontal scrollbar rail.
`railXColors`	group-[&.ps--active-x]/ps:bg-transparent hover:!bg-[#eee] focus:!bg-[#eee] [&.ps--clicking]:!bg-[#eee] dark:hover:!bg-[#555] dark:focus:!bg-[#555] dark:[&.ps--clicking]:!bg-[#555]	Adds styles for horizontal scrollbar rail. Decides the color of the x rail.
`railXThumb`	absolute bottom-0.5 rounded-md h-1.5 group-focus/ps:opacity-100 group-active/ps:opacity-100 [transition:background-color_.2s_linear,_height_.2s_ease-in-out] group-hover/x:h-[11px] group-focus/x:h-[0.6875rem] group-[&.ps--clicking]/x:bg-[#999] group-[&.ps--clicking]/x:h-[11px] outline-none	Adds styles for horizontal scrollbar thumb.
`railXThumbColors`	bg-[#aaa] group-hover/x:bg-[#999] group-focus/x:bg-[#999]	Adds styles for horizontal scrollbar thumb. Decides the color of the x thumb.
`railY`	group/y absolute right-0 w-[0.9375rem] hidden opacity-0 transition-[background-color,_opacity] duration-200 ease-linear motion-reduce:transition-none z-[1035] group-[&.ps--active-y]/ps:block group-hover/ps:opacity-60 group-focus/ps:opacity-60 group-[&.ps--scrolling-y]/ps:opacity-60 hover:!opacity-90 focus:!opacity-90 [&.ps--clicking]:!opacity-90 outline-none	Adds styles for vertical scrollbar rail.
`railYColors`	group-[&.ps--active-y]/ps:bg-transparent hover:!bg-[#eee] focus:!bg-[#eee] [&.ps--clicking]:!bg-[#eee] dark:hover:!bg-[#555] dark:focus:!bg-[#555] dark:[&.ps--clicking]:!bg-[#555]	Adds styles for vertical scrollbar rail. Decides the color of the y rail.
`railYThumb`	absolute right-0.5 rounded-md w-1.5 group-focus/ps:opacity-100 group-active/ps:opacity-100 [transition:background-color_.2s_linear,_width_.2s_ease-in-out,_opacity] group-hover/y:w-[11px] group-focus/y:w-[0.6875rem] group-[&.ps--clicking]/y:w-[11px] outline-none	Adds styles for vertical scrollbar thumb.
`railYThumbColors`	bg-[#aaa] group-hover/y:bg-[#999] group-focus/y:bg-[#999] group-[&.ps--clicking]/y:bg-[#999]	Adds styles for vertical scrollbar thumb. Decides the color of the y thumb.

Methods

Method	Description	Example
`dispose`	Destroy PerfectScrollbar instance.	`myPs.dispose()`
`getInstance`	Static method which allows you to get the perfect scrollbar instance associated to a DOM element.	`PerfectScrollbar.getInstance(myPs)`
`getOrCreateInstance`	Static method which returns the perfect scrollbar instance associated to a DOM element or create a new one in case it wasn't initialized.	`PerfectScrollbar.getOrCreateInstance(myPs)`
`update`	Update PerfectScrollbar	`myPs.update()`

javascript
umd

ES UMD

        
            
        const myPs = document.getElementById('myPsID')
        const ps = new PerfectScrollbar(myPs)
        ps.dispose()

        
            
        const myPs = document.getElementById('myPsID')
        const ps = new te.PerfectScrollbar(myPs)
        ps.dispose()

Events

Event type	Description
`scrollX.te.ps`	This event fires when the x-axis is scrolled in either direction.
`scrollY.te.ps`	This event fires when the y-axis is scrolled in either direction.
`scrollUp.te.ps`	This event fires when scrolling upwards.
`scrollDown.te.ps`	This event fires when scrolling downwards.
`scrollLeft.te.ps`	This event fires when scrolling to the left.
`scrollRight.te.ps`	This event fires when scrolling to the right.
`scrollYStart.te.ps`	This event fires when scrolling reaches the start of the y-axis.
`scrollXStart.te.ps`	This event fires when scrolling reaches the start of the x-axis.
`scrollXEnd.te.ps`	This event fires when scrolling reaches the end of the x-axis.
`scrollYEnd.te.ps`	This event fires when scrolling reaches the end of the y-axis (useful for infinite scroll).

JavaScript

        
            
        const myPs = document.getElementById('element-id')
        myPs.addEventListener('scrollYEnd.te.ps', (e) => {
          // do something...
        })

Tailwind Scrollbar method

Basic example

Options

JavaScript init

Data attributes

Colors example

Events

Example

Scroll exmaple

Tailwind Scrollbar method - API

Import

Usage

Via data attributes

Via JavaScript

Options

Classes

Methods

Events

Tailwind Scrollbar method

Tailwind CSS Scrollbar

Basic example

Options

JavaScript init

Data attributes

Colors example

Events

Example

Related resources

Tailwind Scrollbar method - API

Import

Usage

Via data attributes

Via JavaScript

Options

Classes

Methods

Events