Skip to content

Latest commit

 

History

History
161 lines (104 loc) · 7.24 KB

README.md

File metadata and controls

161 lines (104 loc) · 7.24 KB
Raw

| Setup Guide | Report new issue

ComposeScrollbars

The ComposeScrollbars is a feature-rich Android Compose UI library that seamlessly incorporates customisable scrollbars, including size, animations, background/knob layer style, and scroll behavior, for a seamless UX.

Features:

  • Advanced Customization: Customize scrollbar size, orientation, gravity and visibility animation.
  • Layers Configuration: Configure background and knob layers with style, appearance and animation.
  • Knob Scroll Behavior: Choose from static, worm, fraction, or exact scroll behaviors for the knob.
  • Scrolls States: Ready for ScrollState, LazyListState, LazyGridState, LazyStaggeredGridState.
  • Custom Content: Design custom backgrounds and knobs when required.
  • Sample App: Explore and experiment with sample app.

Sample App

Sample 1 Sample 2 Sample 3
Sample 4 Sample 5 Sample 6

Download or clone this repository to discover the sample app.

Setup

Add to the root build.gradle.kts:

allprojects {
    repositories {
        ...
        maven("https://jitpack.io")
    }
}

Add to the package build.gradle.kts:

dependencies {
    implementation("com.github.GIGAMOLE:ComposeScrollbars:{latest-version}")
}

Latest version: .

Also, it's possible to download the latest artifact from the releases page.

Guide

The ComposeScrollbars comes with the main component: Scrollbars.

For more technical and detailed documentation, read the library KDoc.

Scrollbars

The Scrollbars presents scrollbars based on the provided ScrollbarsState.

Just place it above (Z-order) of your scrollable content so its visible.

ScrollbarsState

The ScrollbarsState consists of two required components: ScrollbarsConfig and ScrollbarsScrollType.

To create a ScrollbarsState, use one of the utility functions: rememberScrollbarsState(...) or make it on your own.

ScrollbarsConfig

The ScrollbarsConfig setups the scrollbars layouts, styles and appearances:

Param Description
orientation The scrollbars orientation: Horizontal or Vertical.
gravity The scrollbars gravity: Start or End.
isReverseLayout The scrollbars reverse layout indicator.
paddingValues The scrollbars layers container padding values.
sizeType The scrollbars layers container size: Full, Fraction or Exact.
layersType The ScrollbarsLayersType.
backgroundLayerContentType The background ScrollbarsLayerContentType.
knobLayerContentType The knob ScrollbarsLayerContentType.
visibilityType The ScrollbarsVisibilityType.
ScrollbarsLayersType

The ScrollbarsLayersType can be one of the following:

  • Wrap: Wraps a knob layer into a background layer. The layers are centered.
  • Split: Splits a knob and a background layer into each own configurable layer.

Each mode can set layers thickness(Exact or Wrap), padding values, and layer gravity (Start, Center or End).

ScrollbarsLayerContentType

The ScrollbarsLayerContentType can be one of the following:

  • None: The empty (not visible) layer content.
  • Custom: Provides custom layer content via the @Composable lambda.
  • Default: The default layer content.

The Default mode can set the content layer shape, style (Backgrond or Border), color (Idle or IdleActive).

ScrollbarsVisibilityType

The ScrollbarsVisibilityType can be one of the following:

  • Static: The static scrollbars visibility.
  • Dynamic: The dynamic scrollbars visibility. Includes in/out animation, fading and other.

The Dynamic mode can be one of the following:

  • Fade: The dynamic visibility with only fade.
  • Slide: The dynamic visibility with the slide, and optional fade.
  • Scale: The dynamic visibility with the scale, and optional fade.

The Dynamic mode can the following UX utility params:

  • isVisibleWhenScrollNotPossible: Indicates whether scrollbars are visible when the scroll is not possible (short content).
  • isVisibleOnTouchDown: Indicates whether scrollbars are visible when any press/touch down event occurred.
  • isStaticWhenScrollPossible: Indicates whether scrollbars are statically visible only when the scroll is possible.

ScrollbarsScrollType

The ScrollbarsScrollType can be one of the following:

  • Scroll: The scrollbars for a ScrollState content.
  • Lazy.List: The scrollbars for a LazyListState content.
  • Lazy.Grid: The scrollbars for a LazyGridState content.
  • Lazy.StaggeredGrid: The scrollbars for a LazyStaggeredGridState content.

The Lazy.List and Lazy.Grid supports the scrollbars for Static or Dynamic items heights.

The Lazy.StaggeredGrid only supports the scrollbars for Dynamic items heights.

Each mode can set the knob size type:

  • Auto: The scrollbars knob with an automatic size.
  • Exact: The scrollbars knob with an exact size.
  • Fraction: The scrollbars knob with a fraction size.
  • Worm: The scrollbars knob with a size, which represents current visible items as a section or with sub-interpolation. Only available for Dynamic item heights.

License

MIT License. See the LICENSE file for more details.

Credits

Special thanks to the GoDaddy for the amazing color picker library.

Author:

Basil Miller
gigamole53@gmail.com