Read page as text

NIB / DOCUMENTATION

Bottom sheet — NibComponents

Let a local task expand between snap heights and return a typed result.

Open interactive view

Reveal a task from the bottom

Use a sheet for a contextual task that benefits from more height: a reading list, filter summary, or item details. NibBottomSheet is an overlay surface, not bottom navigation. The example starts at the smaller snap, expands through an explicit action, and returns a string when the list is chosen.

showNibBottomSheet<T> returns a Future. openNibBottomSheet<T> returns NibBottomSheetHandle<T> with closed, isOpen, close(result), and snapTo(index). The widget NibBottomSheet uses a trigger or NibBottomSheetController. The three preview buttons exercise each ownership model.

Understand fractions and normalized indexes

snapPoints are fractions of available height, not pixels. normalizeSnapExtents clamps them to .05 through 1, removes duplicates, and sorts ascending. Null or an empty list means a content-sized sheet with one implicit snap. kNibSheetMinExtent exposes the .05 minimum.

initialSnap is an index into the normalized list. Null selects the last snap. clampInitialSnapIndex clamps negative indexes to zero and high indexes to the last index. An unsorted input list does not retain its original indexes. These details follow the implementation, including the negative-index case.

final snaps = normalizeSnapExtents([.85, .45, .85])!; // [.45, .85]
final index = clampInitialSnapIndex(snaps.length, 0); // 0
// Pass these same normalized values to the sheet.

Know what a drag release means

resolveSnapTarget is the pure helper used to settle a drag. velocity is measured in extent-fractions per second, positive when opening upward. kNibSheetFlingVelocity defaults to 2. A fast release steps to the next snap; a downward release below the lowest snap can dismiss only if dismissible is true.

A slow release chooses the nearest snap, or dismisses below half the lowest extent when permitted. Do not pass raw pointer pixels per second to this helper. The widget converts using available height. snapTo requests a snap index; onSnapChanged reports the selected index. The example asserts a real height change after expanding.

Expand or finish from inside

NibBottomSheetScope.of(sheetContext) exposes snapTo, close, and isOpen inside content. Expand sheet requests index 1. Use reading list returns a string. A dismissal returns null. After awaiting, check mounted before updating the caller.

Use Builder inside content to obtain the scope. For an external command retain a handle or controller rather than a BuildContext. The complete example captures a scope close callback while active, then closes its imperative surface during disposal.

Own controllers and presentation

NibBottomSheetController exposes open, close, snapTo, isOpen, pendingSnap, and consumePendingSnap. The last two form the handoff used by the attached widget; let it consume requests. Dispose an external controller in its owner. The widget owns its internal controller when none is supplied.

title, showDragHandle, dismissible, and barrierColor describe the surface. animated defaults to false; transition configures optional movement. The root overlay captures the inherited theme and supplies a focus scope. These website sheet tasks are page-modal; a visible completion action remains when outside dismissal is off.

Design for the smallest useful height

Scrolling content does not eliminate the space needed by headers and actions. Test the smallest snap with long labels, text scaling, and keyboard insets. The preview permits a first snap from 30 to 60 percent to keep its actions reachable; that range is an example choice, not a package limit.

Close or cancel work when the workflow leaves the page. VM tests cover returned results and numeric expansion, but physical dragging, platform keyboard insets, and screen-reader behavior remain separate checks. A sheet is not an authorization or data-persistence layer.