API reference#

Exports of @sigx/lynx-list v0.27.0.

Exports#

import { List, ListMethods } from '@sigx/lynx-list';
import type { ListProps, ListRef } from '@sigx/lynx-list';

<List> props#

items and renderItem are the only required props; both are generic over the element type T of items.

Events#

Slots#

Passed through the slots prop.

ListMethods#

Typed wrappers around the native scroll UI methods, callable from any main-thread event handler. Both accept el | null, so you can pass ref.current directly; a null element is a silent no-op.

ListMethods.scrollToTop(el);                          // jump to top
ListMethods.scrollToTop(el, { smooth: true });        // animated
ListMethods.scrollToIndex(el, 12, { align: 'middle', smooth: true });

• scrollToTop(el, opts?) — scroll to the first cell (the top of the list, header included).
• scrollToIndex(el, index, opts?) — scroll so the cell at index aligns per opts.align. index is the rendered cell index, not the data index — add 1 to a data index when a header slot is present.

ScrollToIndexOptions:

scrollHandle#

ListMethods needs the native element. scrollHandle is the prop form — pass an identity-stable handle and the List populates it at setup:

// Module or component scope — NOT inside render. The handle must keep its identity.
const handle: ListScrollHandle = {};

<List scrollHandle={handle} … />

handle.scrollToEnd?.();                  // jump to the newest
handle.scrollToEnd?.({ smooth: true });

scrollToEnd is the one piece of index math you cannot do yourself once windowing is on: it accounts for the header, footer and loading cells and the rendered window. In chat mode it also marks the viewport at-bottom and clears the unread affordance, so a target cell that has not reached native yet is caught by the next relayout's re-pin.

The handle must be identity-stable — build it once, outside render.

itemSnap#

Snaps cells into place when a paginated scroll settles — the native item-snap contract, which both platforms read as a dictionary.

type ListItemSnap = 'start' | 'center' | 'end' | {
  /** Where the item settles, as a fraction of the viewport: 0 start, 0.5 centre, 1 end. Default 0. */
  factor?: number;
  /** Pixel offset from the alignment line. Default 0. */
  offset?: number;
  /** How many items a single fling may cross (Lynx 4.0+). Default 1. */
  maxSnapCount?: number;
};

The shorthand maps to factor 0 / 0.5 / 1. A factor outside [0, 1] is corrected to 0 and a maxSnapCount below 1 to 1 — what native does — with a dev-build warning. maxSnapCount is a bound, not a forced distance: a slow fling still moves one page; a fast one may page up to that many. Hosts older than Lynx 4.0 ignore it. To disable snapping, omit the prop — an absent item-snap is what native means by "no paging".

<List horizontal itemSnap="center" … />
<List horizontal itemSnap={{ factor: 0, offset: 16, maxSnapCount: 3 }} … />

Sticky section headers (sticky-top / sticky-bottom) use the engine's sticky layout; pluginSigxLynx({ enableNewSticky: true }) opts into Lynx 4.0's new implementation, which changes where and when a header pins — see the plugin's page-config flags.

bottomInset#

The recycler keeps bottomInset pixels of its bottom viewport clear. It is applied natively, as a padding/inset delta rather than a CSS write, so there is no layout pass and a main-thread SharedValue — useKeyboardLiftSV(), a BottomSheet's onReveal — can drive it every frame:

const lift = useKeyboardLiftSV();

<List inverted bottomInset={lift} … />

In chat mode the newest item stays anchored above the inset via same-frame native compensation, and at-bottom detection becomes inset-aware — so a compensation scroll cannot falsely release the pin or fire a spurious endReached. The native compensation is gated on the list being pinned at the bottom, which is why the first paint of a chat thread lands on the newest message on both platforms: the pin is established before the inset is applied. No paddingBottom workaround is needed on either platform.

See Usage for worked examples of each feature.