diff --git a/contributingGuides/SELECTION_LIST.md b/contributingGuides/SELECTION_LIST.md index a994e2584dd9..cbb8d7083afe 100644 --- a/contributingGuides/SELECTION_LIST.md +++ b/contributingGuides/SELECTION_LIST.md @@ -74,6 +74,17 @@ There are two main components: /> ``` +## Pinning the pre-selected item + +A searchable list focuses its search input on open, so on mobile the keyboard covers most of the list. When the list can have a pre-selected item, pin that item to the top so it stays visible instead of hiding in its natural position below the fold. + +- Snapshot the selected value when the list opens (for example with `useInitialValue`) so a later tap does not reorder the list mid-interaction. +- Pin it to the top of the full list **before** filtering with `moveInitialSelectionToTop` (from `@libs/SelectionListOrderUtils`). It no-ops for lists below `CONST.STANDARD_LIST_ITEM_LIMIT`, so short lists keep their natural order. +- Any clear/"None" row belongs directly **below** the pinned selection. +- Pages built on `SelectionScreen` get this automatically from `useSelectionListSearch`, which pins the frozen selection and returns `pinnedValues` for callers that need to know what was pinned. + +This is enforced in review by [UI-6](../.claude/skills/app-coding-standards/rules/ui-6-pin-initial-selection.md). + ## Related Components - `SelectionScreen` - Wrapper component that includes screen layout (1 section)