limestone/Scroller

Provides Limestone-themed scroller components and behaviors.

Loading Live Preview

Members

Scroller Component

A Limestone-styled Scroller, useScroll applied.

Usage:

<Scroller>Scroll me.</Scroller>

Extends: ui/Scrollerui/Scroller.ScrollerBasic

Properties

aria-label

String

The "aria-label" for the Scroller.

When aria-label is set and focusableScrollbar is byEnter, it will be used instead to provide an accessibility label for the Scroller.

cbScrollTo

Function

A callback function that receives a reference to the scrollTo feature.

Once received, the scrollTo method can be called as an imperative interface.

{position: {x, y}} - Pixel value for x and/or y position
{align} - Where the scroll area should be aligned. Values are: 'left', 'right', 'top', 'bottom', 'topleft', 'topright', 'bottomleft', and 'bottomright'.
{node} - Node to scroll into view
{animate} - When true, scroll occurs with animation. When false, no animation occurs.
{focus} - When true, attempts to focus item after scroll. Only valid when scrolling by node.

Note: Only specify one of: position, align, node

Example:

// If you set cbScrollTo prop like below;
cbScrollTo: (fn) => {this.scrollTo = fn;}
// You can simply call like below;
this.scrollTo({align: 'top'}); // scroll to the top

data-webos-voice-disabled

Boolean

Disable voice control feature of component.

data-webos-voice-focused

Boolean

Activates the component for voice control.

data-webos-voice-group-label

String

The voice control group label.

direction

'both''horizontal''vertical'

Direction of the scroller.

Default: 'both'

editable

limestone/Scroller.EditableShape

Enables editing items in the scroller. You can specify props for editable scroller as an object. See the details in limestone/Scrollerlimestone/Scroller.EditableShape

fadeOut

Boolean

Adds fade-out effect on the scroller.

Set this to true only if the content has no spottable but text.

Note: Fade-out effect will not show if the direction is set to both.

Default: false

focusableScrollbar

Boolean'byEnter'

Allows 5-way navigation to the scroll thumb.

By default, 5-way will not move focus to the scroll thumb. If true, the scroll thumb will get focus by directional keys. If 'byEnter', scroll thumb will get focus first by directional keys, then the scroll body will get focus by enter key or back key pressed on scroll thumb.

Default: false

horizontalScrollbar

'auto''visible''hidden'

Specifies how to show horizontal scrollbar.

Default: 'auto'

horizontalScrollThumbAriaLabel

String

Sets the hint string read when focusing the scroll thumb in the horizontal scroll bar.

Default: $L('scroll up or down with up down button')

hoverToScroll

Boolean

Enables scroll by hover on edges in scroll direction.

id

String

Unique identifier for the component.

When defined and when the Scroller is within a limestone/Panelslimestone/Panels.Panel, the Scroller will store its scroll position and restore that position when returning to the Panel.

noScrollByWheel

Boolean

Prevents scroll by wheeling on the scroller.

Default: false

onScroll

Function

Called when scrolling.

Passes scrollLeft, scrollTop. It is not recommended to set this prop since it can cause performance degradation. Use onScrollStart or onScrollStop instead.

onScrollStart

Function

Called when scroll starts.

Passes scrollLeft and scrollTop.

Example:

onScrollStart = ({scrollLeft, scrollTop}) => {
    // do something with scrollLeft and scrollTop
}

render = () => (
    <Scroller
        ...
        onScrollStart={this.onScrollStart}
        ...
    />
)

onScrollStop

Function

Called when scroll stops.

Passes scrollLeft and scrollTop.

Example:

onScrollStop = ({scrollLeft, scrollTop}) => {
    // do something with scrollLeft and scrollTop
}

render = () => (
    <Scroller
        ...
        onScrollStop={this.onScrollStop}
        ...
    />
)

scrollbarTrackCss

Object

Customizes the component by mapping the supplied collection of CSS class names to the corresponding internal elements and states of this component.

The following classes are supported:

scrollbarTrack - The scrollbarTrack component class
thumb - The scrollbar thumb component class

scrollMode

'native''translate'

Specifies how to scroll.

Default: 'native'

scrollToContentContainerOnFocus

Boolean

Scrolls to the container created by limestone/Scrollerlimestone/Scroller.ContentContainerDecorator when descendants get focused.

Default: true

stickTo

'start'

Anchors the focused item to a fixed "focus position" while the content scrolls beneath it.

When set to 'start' and direction is 'horizontal', moving focus with 5-way keys keeps the focus indicator at a fixed slot near the start (left in LTR, right in RTL) edge of the scroller and scrolls the list so the newly focused item lands in that slot. At the end of the list, when the item can no longer reach the fixed slot, the list scrolls only to its last position so the focused item (including its full width) stays visible.

By default (undefined), the scroller scrolls just enough to bring the focused item into view.

verticalScrollbar

'auto''visible''hidden'

Specifies how to show vertical scrollbar.

Default: 'auto'

verticalScrollThumbAriaLabel

String

Sets the hint string read when focusing the scroll thumb in the vertical scroll bar.

Default: $L('scroll left or right with left right button')

ContentContainerDecorator Higher-Order Component

Wraps a component to be a scroll target when its descendants get focused.

EditableWrapper Component

A Limestone-styled EditableWrapper.

Properties

editable

limestone/Scroller.EditableShape

Enables editing items in the scroller. You can specify props for editable scroller as an object. See the details in limestone/Scrollerlimestone/Scroller.EditableShape

scrollContainerHandle

FunctionObject

Obtains a reference to the scroll container handle.

scrollContainerRef

FunctionObject

Obtains a reference to the scroll container node.

scrollContentRef

FunctionObject

Obtains a reference to the scroll content node.

Type Definitions

EditableShape Object

The shape for editable of limestone/Scrollerlimestone/Scroller.

• onComplete

Function

The callback function called when editing is finished. It has an event object contains orders array which app can use for repopulate items.

• blurItemFuncRef

Function | Object

Obtains a reference to blurItem function. If you would like to remove focused CSS class to an item, you can get the reference to blurItem function via useRef. blurItem function needs to be called with an item node when an item is blurred.

• centered

Boolean

Centers the contents of the scroller.

• css

Object

Customizes the component by mapping the supplied collection of CSS class names to the corresponding internal elements and states of this component. The following classes are supported:

wrapper - The content wrapper component class
selected - The selected item class
focused - The focused item class

• focusItemFuncRef

Function | Object

Obtains a reference to focusItem function. If you would like to use focused CSS class to an item, you can get the reference to focusItem function via useRef. focusItem function needs to be called with an item node when an item is focused.

• hideItemFuncRef

Function | Object

Obtains a reference to hideItem function. If you would like to hide an item, you can get the reference to hideItem function via useRef.

• removeItemFuncRef

Function | Object

Obtains a reference to removeItem function. If you would like to remove an item, you can get the reference to removeItem function via useRef.

• selectItemBy

string

Decides how to start editing items. It can be either 'press' or 'longPress'. If unset, it defaults to 'longPress'.

• showItemFuncRef

Function | Object

Obtains a reference to showItem function. If you would like to show an item, you can get the reference to showItem function via useRef.