react-native-selection-mode

Library to handle selection mode.

Installation

npm install react-native-selection-mode
# or
yarn add react-native-selection-mode

Observations

There are a few observations to know before using this library:

• Only function components are supported.
• Should work without React Native as long as you can detect the long press gesture or activate the selection mode manually.
• The example app and Usage section contains React Native code. However, you can adapt it if you don't use React Native.

Usage

• The item component that is shown in your list

  // ListItem.tsx
  
  import { Pressable } from "react-native"
  import { Gesture, GestureDetector } from "react-native-gesture-handler"
  import { SelectableItem, useSelectableItem } from "react-native-selection-mode"
  
  
  export interface ListItemProps extends SelectableItem {}
  
  
  export function ListItem(props: ListItemProps) {
  
  
      const { onPress, onLongPress } = useSelectableItem(props)
  
  
      const longPressGesture = Gesture.LongPress()
          .maxDistance(30)
          .minDuration(400)
          .onStart(event => onLongPress())
  
  
      return (
          <GestureDetector gesture={longPressGesture}>
              <Pressable onPress={onPress}>
                  {/* ... */}
              </Pressable>
          </GestureDetector>
      )
  }

• The screen, page or component that contains a list

  // List.tsx
  
  import { useState } from "react"
  import { ListRenderItemInfo } from "react-native"
  import { useSelectionMode } from "react-native-selection-mode"
  
  import { ListItem } from "./ListItem"
  
  
  export function List() {
  
  
      const [data, setData] = useState<number[]>([])
      const listSelection = useSelectionMode<number>()
  
  
      function renderItem({ item, index }: ListRenderItemInfo<number>) {
          return (
              <ListItem
                  isSelectionMode={listSelection.isSelectionMode}
                  isSelected={listSelection.isSelected(index)}
                  onClick={() => console.log("Click")}
                  onSelect={() => listSelection.select(index)}
                  onDeselect={() => listSelection.deselect(index)}
              />
          )
      }
  
  
      return (
          <FlatList
              data={data}
              renderItem={renderItem}
          />
      )
  }

API

Hook useSelectionMode

function useSelectionMode<T>(): SelectionMode<T>

This is the hook that controls the selection mode. It should be used in you list component.

The returned object is described at Interface SelectionMode

Interface SelectionMode<T>

Contains functions that controls the selection and variables about the selection state.

T is the data type that represents the selected item.

Important: Prefer unique data for each item, such as id, index or uuid. If you choose the item itself, make sure it is not repeated. Otherwise it may cause bugs.

• isSelectionMode

  isSelectionMode: boolean

  Indicates whether the selection mode is active or not.

• getSelectedData

  function getSelectedData(): T[]

  Returns: The selected data as array.

• setNewSelectedData

  function setSelectedData(data: Set<T> | ((current: Set<T>) => Set<T>)): void

  Sets the selected data.

  Useful if you want to toggle the selection or handle the selected data in a complex way.

  • If the selection mode is active and the new value is an empty set, the selection mode will be deactivated.
  • If the selection mode is not active and the new value is not an empty set, the selection mode will be activated.

  Attention:

  • This function uses the Set data structure. The type of its params may change in the future according to the internal implementation.
  • The value passed to this function will replace the current selected data.

  Params:

  • newValue: The new selected data. Can be a Set or a function that receives the current selected data and returns a one. Similar to the setState function.

• length

  length: number

  The number of selected items.

• isSelected

  function isSelected(item: T): boolean

  Checks if the item is selected.

  Params:

  • item: The item to be checked.

  Returns: true if the item is selected, false otherwise.

• select

  function select(item: T): void

  Selects the item.

  • If the item is already selected, nothing happens.
  • If the selection mode is not active, it will be activated.

  Params:

  • item: The item to be selected.

• deselect

  function deselect(item: T): void

  Deselects the item.

  • If the item is not selected, nothing happens.
  • If there is no item selected after deselect, the selection mode will be deactivated.

  Params:

  • item: The item to be deselected.

• exitSelection

  function exitSelection(): void

  Exits the selection mode and deselects all items.

Hook useSelectableItem

function useSelectableItem<T extends SelectableItem>(props: T): UseSelectableItem

Consumes the selection mode from useSelectionMode passed to the component through SelectableItem interface. Its returned object is UseSelectableItem. This hook must be called in the items components.

Interface SelectableItem

Contains properties and functions about the selection mode to be handled by useSelectableItem.

• onClick

  function onClick(): void

  Function called when the item is clicked and the component is not in selection mode. Similar to onPress.

• onSelect

  function onSelect(): void

  When in selection mode, this function is called when the item is not selected and is pressed.

  If you want to select the item, you still have to call useSelectionMode().select().

• onDeselect

  function onDeselect(): void

  When in selection mode, this function is called when the item is is selected and is pressed.

  If you want to deselect the item, you still have to call useSelectionMode().deselect().

• isSelectionMode

  isSelectionMode: boolean

  Indicates the selection mode state to the component.

• isSelected

  isSelected: boolean

  Indicates if the component is selected.

Interface UseSelectableItem

The object's type returned by useSelectableItem. It contains functions to be used by a selectable list item. Those functions manages when to call onClick, onSelect and onDeselect according to selection mode and the item's selection, as the same click event can represent different action in the context of selection mode.

• onPress

  function onPress(): void

  This function should be passed to the components onPress or onClick prop. It handles whether to call onClick, onSelect or onDeselect from SelectableItem.

• onLongPress

  function onLongPress(): void

  This function should be called when the component receives a long press or when you want to select the item and activate the selection mode.

  The difference between onLongPress and SelectionMode.select is that onLongPress will only select the item and activate the selection mode if the selection mode is not active when called.