Scrollable

Docs

Scrollable

Tailwind Scrollable makes it easy to add vertically or horizontally scrollable sections with custom scrollbar styles, perfect for long lists, data tables, or extended content.

Examples

Basic Usage

To implement a custom scrollable content with a fixed height, simply utilize the kt-scrollable custom class. This class is designed to create a improved scrollable area within your HTML document.

Horizontal

Below example demonstrates horizontally scrollable content.

Both Scrollbars

Below example demonstrates a scrollable content with bith horizontal and vertical scrollbars.

Auto Height

Use data-kt-scrollable="true" to auto initialize the Tailwind KTScrollable component that dynamically calculates the height of the scrollable content by subtracting the the total heights of specific elements defined via data-kt-scrollable-dependencies="#header, #footer" the total spacings of specific elements defined via data-kt-scrollable-wrappers="#header, #footer" within the HTML document.

<div
  class="flex flex-col w-full h-full rounded-md border border-border overflow-hidden"
>
  <div id="header" class="p-4 font-semibold border-b border-border">Header</div>
  <div
    id="content"
    class="kt-scrollable grow overflow-y-auto p-4 pe-2 w-full"
    data-kt-scrollable="true"
    data-kt-scrollable-height="auto"
    data-kt-scrollable-dependencies="#header,#footer"
    data-kt-scrollable-wrappers="#content"
    data-kt-scrollable-offset="10px"
  >
    <div class="rounded-lg bg-muted w-full grow h-[1000px]"></div>
  </div>
  <div id="footer" class="p-4 text-sm border-t border-border">Footer</div>
</div>

Apply the kt-scrollable-y class to the modal body element to enable vertical scrolling within the scrollable body.

<div>
  <button class="kt-btn" data-kt-modal-toggle="#modal">Show Modal</button>
  <div class="kt-modal" data-kt-modal="true" id="modal">
    <div class="kt-modal-content max-w-[400px] top-[10%]">
      <div class="kt-modal-header">
        <h3 class="kt-modal-title">Modal Title</h3>
        <button
          class="kt-modal-close"
          aria-label="Close modal"
          data-kt-modal-dismiss="#modal"
        >
          <svg
            xmlns="http://www.w3.org/2000/svg"
            width="24"
            height="24"
            viewBox="0 0 24 24"
            fill="none"
            stroke="currentColor"
            stroke-width="2"
            stroke-linecap="round"
            stroke-linejoin="round"
            class="lucide lucide-x"
          >
            <path d="M18 6 6 18"></path>
            <path d="m6 6 12 12"></path>
          </svg>
        </button>
      </div>
      <div class="kt-modal-body max-h-[200px] pe-2">
        <div class="rounded-lg bg-muted w-full grow h-[600px]"></div>
      </div>
      <div class="kt-modal-footer justify-end gap-2.5">
        <button
          type="button"
          class="kt-btn kt-btn-secondary"
          data-kt-modal-dismiss="#modal"
        >
          Cancel</button
        ><button class="kt-btn">Submit</button>
      </div>
    </div>
  </div>
</div>

Customization

Customize the scrollbar thumb color to match your design requirements using the CSS variable for default and dark demos using [--tw-scrollbar-thumb-color:red] and [--tw-scrollbar-thumb-color-dark:yellow] classes.

<div
  class="kt-scrollable [--kt-scrollable-thumb-color:red] overflow-y-auto p-4 pe-2 h-[300px] w-full rounded-lg border border-border"
>
  <div class="rounded-lg bg-muted w-full grow h-[1000px]"></div>
</div>

Component API

Options

These data attributes allow you to set options for the scrollable component during auto initialization.

Option	Type	Default	Description
`data-kt-scrollable-save`	~~boolean~~	~~true~~	Enables saving the last scroll position in browser storage.
`data-kt-reparent-target`	~~string~~	-	Specifies the comma-separated IDs of elements whose heights are calculated and subtracted from the window offset height to determine scrollable height.
`data-kt-scrollable-wrappers`	~~string~~	-	Specifies the comma-separated IDs of elements whose spacings(margin, padding, border widths) are calculated and subtracted from the window offset height to determine scrollable height.
`data-kt-scrollable-offset`	~~string~~	~~"0px"~~	Specifies the offset CSS value in pixel to subtract from the calculated height.

Selectors

This table details the custom classes and data attributes used by the scrollable component.

Name	Description
Data Attributes
`data-kt-scrollable="true"`	Automatically initializes KTScrollable instances on page load.
Classes
`kt-scrollable`	Adds both horizontal and vertical scrolling to the content.
`kt-scrollable-x`	Adds horizontal scrolling to the content.
`kt-scrollable-y`	Adds vertical scrolling to the content.
`kt-scrollable-auto`	Automatically adds scrolling based on content overflow.
`kt-scrollable-x-auto`	Automatically adds horizontal scrolling based on content overflow.
`kt-scrollable-y-auto`	Automatically adds vertical scrolling based on content overflow.
`kt-scrollable-hover`	Adds scrollbars on hover.
`kt-scrollable-x-hover`	Adds horizontal scrollbars on hover.
`kt-scrollable-y-hover`	Adds vertical scrollbars on hover.

Methods

Use KTScrollable component's API methods to programmatically control its behavior.

Method	Description
`update()`	Updates the calculated height.
`getHeight()`	Returnes calculated height.
`getOption(name)`	Retrieves the value of a configuration option by ~~name~~ parameter from a KTScrollable instance.
`getElement()`	Retrieves the DOM element linked to a specific KTScrollable instance.
`on(eventName, handler)`	Allows attaching event listeners to the KTScrollable custom events using the ~~eventName~~ and ~~eventId~~ string parameters. These events enable programmatic interaction based on user actions or internal state changes of KTScrollable. The function returns ~~string~~ as a unique identifier for the registered listener, allowing you to remove it later if needed.
`off(eventName, eventId)`	Removes an event listener for the ~~eventName~~ and ~~eventId~~ parameters attached with the on method.
`dispose()`	Removes the KTScrollable instance from an element, including any associated data stored on the DOM element.

const scrollableEl = document.querySelector('#my_scrollable');
const scrollable = KTScrollable.getInstance(scrollableEl);
 
const height = scrollable.getHeight();
scrollable.update();

To initialize Tailwind Scrollable with JavaScript, use data-scrollable="false" attribute instead. This prevents automatic initialization on page load.

Utilities

Manage and interact with KTScrollable instances using these static methods of KTScrollable JavaScript class.

Method	Description
`init()`	Automatically initializes ~~KTScrollable~~ object for all elements with the data-kt-scrollable attribute on page load.
`createInstances()`	Allows to create KTScrollable instances for all elements that have been dynamically added to the DOM but haven't been activated yet.
`getInstance(element)`	Returns the ~~KTScrollable~~ object associated with the given DOM element ~~element~~ .
`getOrCreateInstance(element)`	Returns the existing ~~KTScrollable~~ object for the provided DOM element ~~element~~ , or creates a new instance if none exists, then returns the same.

// Initialize all scrollables
KTScrollable.init()
 
// Initialzie pending scrollables
KTScrollable.createInstances();
 
// Get scrollable object
const scrollableEl = document.querySelector('#my_scrollable');
const scrollable = KTScrollable.getInstance(scrollableEl);

Events

PreviouseReparent NextScrollspy

On This Page

Examples
Component API

Scrollable

Examples

Basic Usage

Horizontal

Both Scrollbars

Auto Height

With Modal

Customization

Component API

Options

Selectors

Methods

Utilities

Events