⚡️Super-fast Tree view with multi-selection capabilities, using checkboxes and search filtering.

npm version License Workflow Status cov Android iOS Web GitHub issues TS Known Vulnerabilities Expo Snack npm bundle size

Using yarn:

yarn add react-native-tree-multi-select

using npm:

npm install react-native-tree-multi-select

Dependencies that need to be installed for this library to work:

1. @shopify/flash-list
2. Icon Library (One of the following):
   • For Expo Apps (including Expo Go): No additional setup is needed. This library automatically uses @expo/vector-icons, which is included in the Expo SDK.
   • For Non-Expo React Native Apps: Install react-native-vector-icons (>=7.1.0) to enable icon support.

Make sure to follow the native-related installation instructions for these dependencies if you are using bare workflow.

• ⚡ Fast: Designed with performance in mind for smooth scrolling and quick selections.
• 🛠️ Highly Customizable: Modify styles, behavior, and use your custom list component to suit your application's needs.
• 🔍 Filterable: Quickly filter through tree nodes and option to select and un-select only the filtered tree nodes.
• ✅ Well Tested: Comprehensive test coverage to ensure reliability and stability.
• 📚 Well Documented: Detailed documentation to get you started and an example app to demo all the features.
• 🌳 Multi-Level Selection: Select individual nodes or entire branches with ease.
• 📦 Supports Large Datasets: Efficiently handles large trees without much performance degradation.
• 🔒 TypeScript Support: Full TypeScript support for better developer experience.
• 💻 Cross-Platform: Works seamlessly across iOS, Android, and web (with React Native Web).

import {
 TreeView,
 type TreeNode,
 type TreeViewRef
} from 'react-native-tree-multi-select';
// Refer to the Properties table below or the example app for the TreeNode type
const myData: TreeNode[] = [...];
export function TreeViewUsageExample(){
 const treeViewRef = React.useRef<TreeViewRef | null>(null);
 
 // It's recommended to use debounce for the search function (refer to the example app)
 function triggerSearch(text: string){
 // Pass search text to the tree along with the keys on which search is to be done(optional)
 treeViewRef.current?.setSearchText(text, ["name"]);
 }
 
 // Callback functions for check and expand state changes:
 const handleSelectionChange = (
 _checkedIds: string[],
 _indeterminateIds: string[]
 ) => {
 // NOTE: Handle _checkedIds and _indeterminateIds here
 };
 const handleExpanded = (expandedIds: string[]) => {
 // NOTE: Do something with updated expandedIds here
 };
 // Expand collapse calls using ref
 const expandAllPress = () => treeViewRef.current?.expandAll?.();
 const collapseAllPress = () => treeViewRef.current?.collapseAll?.();
 const expandNodes = (idsToExpand: string[]) => treeViewRef.current?.expandNodes?.(
 idsToExpand
 );
 const collapseNodes = (idsToCollapse: string[]) => treeViewRef.current?.collapseNodes?.(
 idsToCollapse
 );
 // Multi-selection function calls using ref
 const onSelectAllPress = () => treeViewRef.current?.selectAll?.();
 const onUnselectAllPress = () => treeViewRef.current?.unselectAll?.();
 const onSelectAllFilteredPress = () => treeViewRef.current?.selectAllFiltered?.();
 const onUnselectAllFilteredPress = () => treeViewRef.current?.unselectAllFiltered?.();
 const selectNodes = (idsToExpand: string[]) => treeViewRef.current?.selectNodes?.(
 idsToSelect
 );
 const unselectNodes = (idsToCollapse: string[]) => treeViewRef.current?.unselectNodes?.(
 idsToUnselect
 );
 
 return(
 // ... Remember to keep a fixed height for the parent. Read Flash List docs to know why
 <TreeView
 ref={treeViewRef}
 data={myData}
 onCheck={handleSelectionChange}
 onExpand={handleExpanded}
 />
 );
}

The TreeViewProps interface defines the properties for the tree view component.

• The ID type parameter allows flexibility in specifying the type of node identifiers (e.g., string, number, or custom types).

• i️ If CustomNodeRowComponent is provided then below props are not applied:

  1. indentationMultiplier
  2. checkBoxViewStyleProps
  3. CheckboxComponent
  4. BuiltInCheckBoxViewStyleProps
  5. ExpandCollapseIconComponent
  6. ExpandCollapseTouchableComponent.

• ⚠️ If the tree view doesn't scroll if rendered in a complex nested scroll view/s then try setting the renderScrollComponent value in treeFlashListProps to ScrollView from react-native-gesture-handler.

The TreeNode interface defines the properties for individual item of the tree view

The TreeViewRef interface defines the properties for the ref object of the tree view component

The SelectionPropagation interface defines the selection propagation behaviour of the tree view

All properties of FlashListProps(from @shopify/flash-list) except for data and renderItem

This interface allows you to customize the style of the built-in checkbox component that is rendered in the tree view by default. Overriden if CustomNodeRowComponent is used.

All properties of CheckboxProps(from @futurejj/react-native-checkbox) except for onPress and status

Type: boolean OR "indeterminate"

• Row Item full-customization
• Prop to control auto children and parents selection. Can now be done using selectionPropagation prop 🎉
• Prop to set the maximum checked item limit
• Prop to disable certain nodes from getting checked
• Ref function to programatically expand/collapse a certain node
• Ref function to programatically un/check a certain node
• Ref function to auto-scroll to a certain node's position - available in 1.9.0+

If you do not see what you want in the planned feature list, raise a feature request.

1. Radio button like selection in tree view: Snack link
2. Display count of number of checked nodes: Snack link

See the contributing guide to learn how to contribute to the repository and the development workflow.

MIT

LiberPay_Donation_Button Paypal_Donation_Button Paypal_Donation_Button

• Module built using create-react-native-library
• To allow super fast list rendering @shopify/flash-list
• Super easy state management done using zustand
• Readme is edited using Typora
• Example app uses @gorhom/showcase-template