### Start Metro Server

Source: https://github.com/azeezat/react-native-select/blob/main/CONTRIBUTING.md

Starts the Metro server for the example application, allowing for live reloading during development.

```sh
yarn start
```

--------------------------------

### Run Example App on iOS

Source: https://github.com/azeezat/react-native-select/blob/main/CONTRIBUTING.md

Builds and runs the example application on an iOS simulator or device.

```sh
yarn ios
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/azeezat/react-native-select/blob/main/CONTRIBUTING.md

Run this command in the root directory to install all necessary dependencies for the project.

```sh
yarn
```

--------------------------------

### Run Example App on Android

Source: https://github.com/azeezat/react-native-select/blob/main/CONTRIBUTING.md

Builds and runs the example application on an Android device or emulator.

```sh
yarn android
```

--------------------------------

### Bootstrap Project Dependencies

Source: https://github.com/azeezat/react-native-select/blob/main/CONTRIBUTING.md

Installs all dependencies and pods to set up the project for development.

```sh
yarn bootstrap
```

--------------------------------

### Install react-native-input-select

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/README.md

Install the library using npm or yarn. Ensure peer dependencies like react and react-native are met, along with react-native-safe-area-context.

```bash
npm install react-native-input-select
# or
yarn add react-native-input-select
```

--------------------------------

### Install CocoaPods Dependencies

Source: https://github.com/azeezat/react-native-select/blob/main/example/README.md

Run these commands for iOS development. The first installs the Ruby bundler, and the second installs CocoaPods dependencies.

```sh
bundle install

bundle exec pod install
```

--------------------------------

### Start Metro Bundler

Source: https://github.com/azeezat/react-native-select/blob/main/example/README.md

Run this command from the root of your React Native project to start the Metro dev server.

```sh
# Using npm
npm start

# OR using Yarn
yarn start
```

--------------------------------

### Install with npm

Source: https://github.com/azeezat/react-native-select/blob/main/README.md

Use this command to add the react-native-input-select package to your project using npm.

```bash
npm install react-native-input-select
```

--------------------------------

### Accessibility Example for DropdownSelect

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/README.md

Demonstrates how to configure accessibility props for screen readers and automation.

```typescript
<DropdownSelect
  testID="country-dropdown"
  accessible
  accessibilityLabel="Country selector"
  accessibilityHint="Double-tap to open list"
/>
```

--------------------------------

### Install with yarn

Source: https://github.com/azeezat/react-native-select/blob/main/README.md

Use this command to add the react-native-input-select package to your project using yarn.

```bash
yarn add react-native-input-select
```

--------------------------------

### CheckBox Example Usage

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/components.md

Demonstrates how to use the CheckBox component with custom labels, values, colors, and styling options.

```typescript
<CheckBox
  label="Accept terms"
  value={accepted}
  onChange={(checked) => setAccepted(checked)}
  primaryColor="blue"
  checkboxControls={{
    checkboxSize: 18,
    checkboxStyle: { borderColor: 'blue' },
  }}
/>
```

--------------------------------

### Build and Run iOS App

Source: https://github.com/azeezat/react-native-select/blob/main/example/README.md

After installing CocoaPods dependencies, use this command to build and run your iOS app with Metro running.

```sh
# Using npm
npm run ios

# OR using Yarn
yarn ios
```

--------------------------------

### Search Scope Example

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/search-functionality.md

Demonstrates how search can match both the 'label' and 'value' properties of options. Users can search by visible text or underlying values.

```typescript
const options = [
  { label: 'New York', value: 'NY' },
  { label: 'California', value: 'CA' },
];

// Both of these searches match "New York":
// - Typing "New"
// - Typing "NY"
```

--------------------------------

### Example Usage of CustomModal

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/components.md

Demonstrates how to use the CustomModal component with custom styling for the overlay and container, and passing children for the modal content.

```jsx
<CustomModal
  visible={isOpen}
  onRequestClose={handleClose}
  modalControls={{
    modalBackgroundStyle: {
      backgroundColor: 'rgba(0, 0, 0, 0.7)',
    },
    modalOptionsContainerStyle: {
      maxHeight: '70%',
      borderRadius: 12,
    },
  }}
>
  {/* List component here */}
</CustomModal>
```

--------------------------------

### DropdownSectionList Example Usage

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/components.md

Example of how to use the DropdownSectionList component with multiple selection enabled. Ensure 'sectionedOptions', 'selected', and 'onChange' are defined in your component.

```typescript
<DropdownSectionList
  options={sectionedOptions}
  optionLabel="name"
  optionValue="id"
  selectedItems={selected}
  isMultiple={true}
  handleMultipleSelections={onChange}
  primaryColor="blue"
/>
```

--------------------------------

### Example Usage of useSearch Hook

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/hooks.md

Demonstrates how to use the useSearch hook to manage search functionality, including accessing search state and filtered options.

```typescript
const {
  searchValue,
  setSearchValue,
  filteredOptions,
  isSectionList
} = useSearch({
  initialOptions: myOptions,
  optionLabel: 'name',
  optionValue: 'id',
  searchCallback: (text) => console.log('User typed:', text),
});
```

--------------------------------

### Input Component Usage

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/components.md

Example of using the Input component for a searchable text field. Customize placeholder, colors, and styles as needed.

```typescript
<Input
  value={searchText}
  onChangeText={setSearchText}
  placeholder="Search items..."
  primaryColor="blue"
  textInputContainerStyle={{ marginVertical: 10 }}
  style={{ fontSize: 14 }}
/>
```

--------------------------------

### Imperative Handle Usage Example

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/types.md

Demonstrates how to use the `useRef` hook to access and call imperative methods like `open` on the DropdownSelect component.

```typescript
const dropdownRef = useRef<DropdownSelectHandle>(null);
dropdownRef.current?.open();
```

--------------------------------

### DropdownFlatList Component Usage

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/components.md

Example of using the DropdownFlatList component for single selection. Configure options, labels, values, and selection handlers.

```typescript
<DropdownFlatList
  options={filteredOptions}
  optionLabel="name"
  optionValue="id"
  selectedItem={selected}
  isMultiple={false}
  handleSingleSelection={onChange}
  primaryColor="green"
/>
```

--------------------------------

### DropdownSelect Accessibility Example

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/ref-handle.md

Shows how to enhance DropdownSelect accessibility using React Native's AccessibilityInfo API. This example announces status updates to screen readers when the dropdown is opened.

```typescript
import React, { useRef, useState } from 'react';
import { View, Button, AccessibilityInfo } from 'react-native';
import DropdownSelect from 'react-native-input-select';
import type { DropdownSelectHandle } from 'react-native-input-select';

function AccessibleDropdown() {
  const dropdownRef = useRef<DropdownSelectHandle>(null);
  const [selected, setSelected] = useState<string>('');

  const handleAccessibleOpen = async () => {
    // Announce to screen readers
    await AccessibilityInfo.announceForAccessibility(
      'Opening dropdown, please wait'
    );
    
    dropdownRef.current?.open();
    
    setTimeout(() => {
      AccessibilityInfo.announceForAccessibility(
        'Dropdown opened. Select an option'
      );
    }, 500);
  };

  return (
    <View style={{ padding: 20 }}>
      <DropdownSelect
        ref={dropdownRef}
        testID="main-dropdown"
        label="Accessible Dropdown"
        placeholder="Choose an option..."
        options={[
          { label: 'Option 1', value: '1' },
          { label: 'Option 2', value: '2' },
          { label: 'Option 3', value: '3' },
        ]}
        selectedValue={selected}
        onValueChange={setSelected}
        accessible
        accessibilityLabel="Dropdown for selecting options"
        accessibilityHint="Double-tap to open the list"
      />

      <Button
        title="Open (Accessible)"
        onPress={handleAccessibleOpen}
        accessibilityLabel="Open dropdown"
      />
    </View>
  );
}

export default AccessibleDropdown;

```

--------------------------------

### Basic Single Select Example

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/dropdown-select.md

Demonstrates a basic single select dropdown. Use `useState` to manage the selected value and `onValueChange` to update it.

```typescript
import React, { useState } from 'react';
import { View } from 'react-native';
import DropdownSelect from 'react-native-input-select';

export function BasicExample() {
  const [country, setCountry] = useState<string>('');

  return (
    <View style={{ padding: 20 }}>
      <DropdownSelect
        label="Select a country"
        placeholder="Choose one..."
        options={[
          { label: 'Nigeria', value: 'NG' },
          { label: 'Canada', value: 'CA' },
          { label: 'Germany', value: 'DE' },
        ]}
        selectedValue={country}
        onValueChange={setCountry}
        primaryColor="blue"
      />
    </View>
  );
}
```

--------------------------------

### useSelectAll Hook Example

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/hooks.md

Manages the 'select all' checkbox state for multiple selections. This hook is useful for implementing bulk selection functionality in lists.

```typescript
const { selectAll, handleSelectAll } = useSelectAll({
  options: visibleOptions,
  selectedItems,
  isMultiple: true,
  onValueChange: updateSelection,
  optionValue: 'id',
  listControls: {
    selectAllCallback: () => analytics.track('selected_all'),
    unselectAllCallback: () => analytics.track('cleared_all'),
  },
});
```

--------------------------------

### Example Usage of useSelectionHandler for Multiple Selections

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/hooks.md

Demonstrates how to use the useSelectionHandler hook for managing multiple selections with specific constraints. Ensure `setFormField` and `closeDropdown` are defined in your scope.

```typescript
const {
  selectedItems,
  handleMultipleSelections,
  setSelectedItems
} = useSelectionHandler({
  initialSelectedValue: [],
  isMultiple: true,
  minSelectableItems: 1,
  maxSelectableItems: 5,
  onValueChange: (values) => setFormField(values),
  closeModal: closeDropdown,
  autoCloseOnSelect: false,
});
```

--------------------------------

### DropdownSelect with Section List

Source: https://github.com/azeezat/react-native-select/blob/main/README.md

Demonstrates how to use the DropdownSelect component with a section list for categorized options. This is useful for organizing large lists of choices. The example shows custom styling for section headers.

```javascript
<DropdownSelect
  label="Menu"
  placeholder="Select multiple dishes..."
  options={[
    {
      title: 'Main dishes',
      data: [
        { label: 'Pizza', value: 'A' },
        { label: 'Burger', value: 'B' },
        { label: 'Risotto', value: 'C' },
      ],
    },
    {
      title: 'Sides',
      data: [
        { label: 'Ice cream', value: 'D' },
        { label: 'Cheesecake', value: 'E' },
      ],
    },
    {
      title: 'Drinks',
      data: [
        { label: 'Water', value: 'F' },
        { label: 'Coke', value: 'G' },
        { label: 'Juice', value: 'H' },
      ],
    },
  ]}
  selectedValue={menu}
  onValueChange={(itemValue: any) => setMenu(itemValue)}
  isMultiple
  isSearchable
  primaryColor={'deepskyblue'}
  listComponentStyles={{
    sectionHeaderStyle: {
      padding: 10,
      backgroundColor: 'green',
      color: 'white',
      width: '30%',
    },
  }}
/>
```

--------------------------------

### List Controls for Multiple Select

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/dropdown-select.md

Enhance multiple select functionality with list controls, including 'Select All' and 'Unselect All' options. This example configures custom text for these controls and provides callbacks for their actions.

```typescript
<DropdownSelect
  label="Select staff"
  isMultiple
  options={staffList}
  selectedValue={selected}
  onValueChange={setSelected}
  listControls={{
    selectAllText: 'Choose Everyone',
    unselectAllText: 'Remove Everyone',
    selectAllCallback: () => console.log('All selected'),
    unselectAllCallback: () => console.log('All deselected'),
    emptyListMessage: 'No staff available',
  }}
/>
```

--------------------------------

### Controlling Dropdown with Ref

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/dropdown-select.md

Control the dropdown's open and close states programmatically using a ref. This example shows how to attach a ref and use buttons to trigger the `open` and `close` methods.

```typescript
import React, { useRef, useState } from 'react';
import { View, Button } from 'react-native';
import DropdownSelect, { DropdownSelectHandle } from 'react-native-input-select';

export function RefControlExample() {
  const dropdownRef = useRef<DropdownSelectHandle>(null);
  const [selected, setSelected] = useState<string>('');

  return (
    <View style={{ padding: 20 }}>
      <DropdownSelect
        ref={dropdownRef}
        label="Select item"
        options={[
          { label: 'Item 1', value: '1' },
          { label: 'Item 2', value: '2' },
        ]}
        selectedValue={selected}
        onValueChange={setSelected}
      />
      <Button title="Open" onPress={() => dropdownRef.current?.open()} />
      <Button title="Close" onPress={() => dropdownRef.current?.close()} />
    </View>
  );
}
```

--------------------------------

### Basic Imperative Control with Ref

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/ref-handle.md

Demonstrates how to use `useRef` to get a handle on the DropdownSelect component and call its `open()` and `close()` methods. This is useful for controlling the dropdown's visibility programmatically.

```typescript
import React, { useRef, useState } from 'react';
import { View, Button } from 'react-native';
import DropdownSelect from 'react-native-input-select';
import type { DropdownSelectHandle } from 'react-native-input-select';

function BasicRefExample() {
  const dropdownRef = useRef<DropdownSelectHandle>(null);
  const [selected, setSelected] = useState<string>('');

  return (
    <View style={{ padding: 20 }}>
      <DropdownSelect
        ref={dropdownRef}
        label="Select an item"
        placeholder="Choose one..."
        options={[
          { label: 'Item 1', value: '1' },
          { label: 'Item 2', value: '2' },
          { label: 'Item 3', value: '3' },
        ]}
        selectedValue={selected}
        onValueChange={setSelected}
      />

      <View style={{ flexDirection: 'row', gap: 10, marginTop: 20 }}>
        <Button 
          title="Open" 
          onPress={() => dropdownRef.current?.open()}
        />
        <Button 
          title="Close" 
          onPress={() => dropdownRef.current?.close()}
        />
      </View>
    </View>
  );
}

export default BasicRefExample;
```

--------------------------------

### useModal Hook Example

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/hooks.md

Controls modal visibility state for the dropdown list. Use this hook to manage the open and close states of a modal dialog.

```typescript
const { isVisible, openModal, closeModal } = useModal({
  resetOptionsRelatedState: resetSearch,
  disabled: false,
  modalControls: { /* ... */ },
});
```

--------------------------------

### Class Component with react-native-select

Source: https://github.com/azeezat/react-native-select/wiki/Class-Component-Example

This snippet shows a basic class component setup using the react-native-select component. It includes state management for the selected item and props for customization.

```typescript
import React, { Component } from 'react';
import { View, Text, StyleSheet } from 'react-native';
import Select from 'react-native-select';

interface State {
  selectedItem: string | null;
}

class App extends Component<{}, State> {
  constructor(props: {}) {
    super(props);
    this.state = {
      selectedItem: null,
    };
  }

  render() {
    const data = [
      { id: '1', value: 'Option 1' },
      { id: '2', value: 'Option 2' },
      { id: '3', value: 'Option 3' },
    ];

    return (
      <View style={styles.container}>
        <Text style={styles.title}>Class Component Example</Text>
        <Select
          data={data}
          onSelect={(item) => this.setState({ selectedItem: item.value })}
          placeholder="Select an option"
          style={styles.select}
        />
        {this.state.selectedItem && (
          <Text style={styles.selectedText}>
            Selected: {this.state.selectedItem}
          </Text>
        )}
      </View>
    );
  }
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    padding: 20,
    backgroundColor: '#f5f5f5',
  },
  title: {
    fontSize: 24,
    fontWeight: 'bold',
    marginBottom: 20,
  },
  select: {
    width: '100%',
    marginBottom: 20,
  },
  selectedText: {
    fontSize: 18,
    marginTop: 10,
    color: '#333',
  },
});

export default App;

```

--------------------------------

### Example Test Pattern

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/README.md

This snippet demonstrates how to use the `testID` prop for identifying the dropdown component in tests. It utilizes React Testing Library's `render` and `getByTestId` functions.

```typescript
const { getByTestId } = render(
  <DropdownSelect
    testID="my-dropdown"
    options={options}
    selectedValue={selected}
    onValueChange={setSelected}
  />
);

const dropdown = getByTestId('my-dropdown');
```

--------------------------------

### Advanced Styling Options

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/dropdown-select.md

Customize the appearance of the dropdown using various style props. This example shows how to apply custom styles to the dropdown container, label, selected item, and multiple selected items.

```typescript
<DropdownSelect
  label="Custom styled dropdown"
  options={options}
  selectedValue={selected}
  onValueChange={setSelected}
  primaryColor="orange"
  dropdownStyle={{
    borderColor: 'orange',
    borderWidth: 2,
    borderRadius: 8,
  }}
  labelStyle={{
    fontSize: 16,
    fontWeight: 'bold',
    color: 'orange',
  }}
  selectedItemStyle={{
    color: 'orange',
    fontWeight: '600',
  }}
  multipleSelectedItemStyle={{
    backgroundColor: 'orange',
    color: 'white',
  }}
/>
```

--------------------------------

### Search with AutoFocus

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/search-functionality.md

Demonstrates how to enable auto-focus on the search input when the dropdown modal opens. This is achieved by setting `autoFocus: true` within the `textInputProps` of `searchControls`. Use this when you want the user to immediately start typing after opening the select component.

```typescript
import React, { useRef, useState } from 'react';
import { View, Button } from 'react-native';
import DropdownSelect from 'react-native-input-select';
import type { DropdownSelectHandle } from 'react-native-input-select';

function SearchWithAutoFocus() {
  const dropdownRef = useRef<DropdownSelectHandle>(null);
  const [selected, setSelected] = useState<string>('');

  const handleOpenAndFocus = () => {
    dropdownRef.current?.open();
    // Search input will auto-focus due to textInputProps
  };

  return (
    <View style={{ padding: 20 }}>
      <DropdownSelect
        ref={dropdownRef}
        label="Quick Search"
        placeholder="Click button to search..."
        isSearchable
        options={[
          { label: 'JavaScript', value: 'js' },
          { label: 'TypeScript', value: 'ts' },
          { label: 'Python', value: 'py' },
          { label: 'Java', value: 'java' },
          { label: 'Go', value: 'go' },
        ]}
        selectedValue={selected}
        onValueChange={setSelected}
        searchControls={{
          textInputProps: {
            autoFocus: true,  // Focus when modal opens
            placeholder: 'Type language name...',
            returnKeyType: 'search',
          },
        }}
      />

      <Button
        title="Open and Search"
        onPress={handleOpenAndFocus}
        color="blue"
      />
    </View>
  );
}

export default SearchWithAutoFocus;
```

--------------------------------

### useIndexOfSelectedItem Hook Example

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/hooks.md

Demonstrates how to use the useIndexOfSelectedItem hook to get the scroll index and set it based on a selected item's label. Ensure 'myOptions' is defined and 'optionLabel' matches the property name for item labels.

```typescript
const { listIndex, setIndexOfSelectedItem } = useIndexOfSelectedItem({
  options: myOptions,
  optionLabel: 'name',
  isSectionList: false,
});

// Scroll to item with label "France"
setIndexOfSelectedItem('France');
```

--------------------------------

### Package.json Exports Configuration

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/MODULE-EXPORTS.md

Defines the entry points for different module systems and environments.

```json
{
  "main": "lib/commonjs/index",
  "module": "lib/module/index",
  "react-native": "src/index",
  "types": "lib/typescript/src/index.d.ts",
  "source": "src/index"
}
```

--------------------------------

### Setting up useRef for DropdownSelect

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/ref-handle.md

Demonstrates how to initialize a ref for the DropdownSelect component to enable imperative control. Ensure you import `useRef` and `DropdownSelectHandle`.

```typescript
import { useRef } from 'react';
import DropdownSelect from 'react-native-input-select';
import type { DropdownSelectHandle } from 'react-native-input-select';

function MyComponent() {
  const dropdownRef = useRef<DropdownSelectHandle>(null);

  return (
    <>
      <DropdownSelect
        ref={dropdownRef}
        // ... other props
      />
    </>
  );
}
```

--------------------------------

### Basic Dropdown Usage

Source: https://github.com/azeezat/react-native-select/blob/main/README.md

Demonstrates how to use the Dropdown component for selecting an option from a list. Set the label, placeholder, options, selected value, and a primary color.

```javascript
import React from 'react';
import Dropdown from 'react-native-input-select';

export default function App() {
  const [country, setCountry] = React.useState();

  return (
    <Dropdown
      label="Country"
      placeholder="Select an option..."
      options={[
        { label: 'Nigeria', value: 'NG' },
        { label: 'Åland Islands', value: 'AX' },
        { label: 'Algeria', value: 'DZ' },
        { label: 'American Samoa', value: 'AS' },
        { label: 'Andorra', value: 'AD' },
      ]}
      selectedValue={country}
      onValueChange={(value) => setCountry(value)}
      primaryColor={'green'}
    />
  );
}
```

--------------------------------

### Basic Search Configuration

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/search-functionality.md

Configure a simple searchable dropdown with a label, placeholder, and a list of options. Use this for straightforward search needs.

```typescript
import React, { useState } from 'react';
import { View } from 'react-native';
import DropdownSelect from 'react-native-input-select';

function BasicSearch() {
  const [selected, setSelected] = useState<string>('');

  return (
    <View style={{ padding: 20 }}>
      <DropdownSelect
        label="Search Countries"
        placeholder="Type to search..."
        isSearchable
        options={[
          { label: 'Nigeria', value: 'NG' },
          { label: 'Canada', value: 'CA' },
          { label: 'Germany', value: 'DE' },
          { label: 'France', value: 'FR' },
          { label: 'Japan', value: 'JP' },
        ]}
        selectedValue={selected}
        onValueChange={setSelected}
        searchControls={{
          textInputProps: {
            placeholder: 'Search by name or code...',
          },
        }}
      />
    </View>
  );
}

export default BasicSearch;
```

--------------------------------

### Publish New Version

Source: https://github.com/azeezat/react-native-select/blob/main/CONTRIBUTING.md

Uses release-it to automate the process of bumping versions, creating tags, and publishing new releases to npm.

```sh
yarn release
```

--------------------------------

### Build and Run Android App

Source: https://github.com/azeezat/react-native-select/blob/main/example/README.md

Execute this command in a new terminal window to build and run your Android app with Metro running.

```sh
# Using npm
npm run android

# OR using Yarn
yarn android
```

--------------------------------

### Basic Dropdown with Validation

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/configuration.md

Configure a simple dropdown with essential props for label, placeholder, options, value selection, and error handling. Includes helper text for user guidance.

```typescript
<DropdownSelect
  label="Country"
  placeholder="Select your country"
  options={countries}
  selectedValue={country}
  onValueChange={setCountry}
  error={errors.country}
  helperText="Required field"
  primaryColor="#FF6B35"
/>
```

--------------------------------

### Configure List Behavior and Text

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/configuration.md

Customize text for select all/unselect all actions, and control the message displayed when the list is empty. Also configure keyboard behavior for better user experience.

```typescript
{
  selectAllText?: string;                   // "Select all" button text (default: 'Select all')
  unselectAllText?: string;                 // "Unselect all" button text (default: 'Clear all')
  selectAllCallback?: () => void;           // Called when select all is triggered
  unselectAllCallback?: () => void;         // Called when unselect all is triggered
  hideSelectAll?: boolean;                  // Hide select all checkbox (default: false)
  emptyListMessage?: string;                // Message when list is empty (default: 'No options available')
  keyboardShouldPersistTaps?: 'always' | 'never' | 'handled';  // Keyboard tap behavior
}
```

```typescript
<DropdownSelect
  isMultiple
  listControls={{
    selectAllText: 'Choose Everything',
    unselectAllText: 'Remove Everything',
    selectAllCallback: () => {
      console.log('User selected all items');
      // Trigger analytics, etc.
    },
    unselectAllCallback: () => {
      console.log('User deselected all items');
    },
    emptyListMessage: 'No items match your search',
    keyboardShouldPersistTaps: 'always',
  }}
/>
```

--------------------------------

### TSectionList Type Definition and Example

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/types.md

Represents an array of section list items with grouping by sections. Used for dropdown options organized into collapsible sections.

```typescript
type TSectionList = TSectionListItem[];
```

```typescript
type TSectionListItem = { title: string; data: TFlatList };
```

```typescript
const options: TSectionList = [
  {
    title: 'Africa',
    data: [
      { label: 'Nigeria', value: 'NG' },
      { label: 'Egypt', value: 'EG' }
    ]
  },
  {
    title: 'Europe',
    data: [
      { label: 'Germany', value: 'DE' },
      { label: 'France', value: 'FR' }
    ]
  }
];
```

--------------------------------

### List Controls Configuration

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/README.md

Configure the behavior and display of the option list. Options include select all/unselect all functionality and messages for empty lists.

```typescript
{
  selectAllText?: string;
  unselectAllText?: string;
  selectAllCallback?: () => void;
  unselectAllCallback?: () => void;
  hideSelectAll?: boolean;
  emptyListMessage?: string;
  keyboardShouldPersistTaps?: 'always' | 'never' | 'handled';
}
```

--------------------------------

### TFlatList Type Definition and Example

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/types.md

Represents an array of flat list items without grouping. Each item is an object with arbitrary properties. Used for simple dropdown options.

```typescript
type TFlatList = TFlatListItem[];
```

```typescript
type TFlatListItem = {
  [key: string]: TSelectedItemWithReactComponent;
};
```

```typescript
const options: TFlatList = [
  { label: 'Nigeria', value: 'NG' },
  { label: 'Canada', value: 'CA' },
  { label: 'Germany', value: 'DE', disabled: true }
];
```

--------------------------------

### Importing DropdownSelect Component

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/dropdown-select.md

Demonstrates how to import the DropdownSelect component from the 'react-native-input-select' library. Two common import syntaxes are shown.

```typescript
import DropdownSelect from 'react-native-input-select';
// or
import { DropdownSelect } from 'react-native-input-select';
```

--------------------------------

### Basic DropdownSelect Usage

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/README.md

Demonstrates how to use the DropdownSelect component to create a basic country selection input. Requires SafeAreaProvider for proper rendering.

```typescript
import React, { useState } from 'react';
import { SafeAreaProvider } from 'react-native-safe-area-context';
import DropdownSelect from 'react-native-input-select';

export default function App() {
  const [country, setCountry] = useState<string>('');

  return (
    <SafeAreaProvider>
      <DropdownSelect
        label="Country"
        placeholder="Select a country..."
        options={[
          { label: 'Nigeria', value: 'NG' },
          { label: 'Canada', value: 'CA' },
          { label: 'Germany', value: 'DE' },
        ]}
        selectedValue={country}
        onValueChange={setCountry}
        primaryColor="blue"
      />
    </SafeAreaProvider>
  );
}
```

--------------------------------

### Custom Checkbox Controls

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/dropdown-select.md

Customize the appearance of checkboxes in multiple select mode. This example demonstrates how to adjust checkbox size, style, label style, and the color for unselected checkboxes.

```typescript
<DropdownSelect
  label="Custom checkboxes"
  isMultiple
  options={options}
  selectedValue={selected}
  onValueChange={setSelected}
  checkboxControls={{
    checkboxSize: 20,
    checkboxStyle: {
      backgroundColor: 'blue',
      borderColor: 'darkblue',
    },
    checkboxLabelStyle: {
      fontSize: 14,
      fontWeight: '500',
    },
    checkboxUnselectedColor: 'lightgray',
  }}
/>
```

--------------------------------

### Import Main DropdownSelect Component

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/INDEX.md

Import the default export for the main DropdownSelect component.

```typescript
import DropdownSelect from 'react-native-input-select';
```

--------------------------------

### Opening the Dropdown Programmatically

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/ref-handle.md

Shows how to use the `open()` method from the ref to programmatically open the dropdown. This method respects the `disabled` prop and resets component state.

```typescript
const dropdownRef = useRef<DropdownSelectHandle>(null);

<Button 
  title="Show Dropdown" 
  onPress={() => dropdownRef.current?.open()}
/>

<DropdownSelect
  ref={dropdownRef}
  options={options}
  selectedValue={selected}
  onValueChange={setSelected}
/>
```

--------------------------------

### Get Selections Data (Single and Multiple Mode)

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/utility-functions.md

Use this function to retrieve the complete option objects for currently selected values. It supports both single and multiple selection modes. Ensure the `optionValue` property correctly identifies the value in your options.

```typescript
import { getSelectionsData } from 'react-native-input-select';

const options = [
  { label: 'Red', value: 'red', hex: '#FF0000' },
  { label: 'Green', value: 'green', hex: '#00FF00' },
  { label: 'Blue', value: 'blue', hex: '#0000FF' },
];

// Single selection
const data = getSelectionsData({
  isMultiple: false,
  optionValue: 'value',
  selectedItem: 'red',
  selectedItems: [],
  modifiedOptions: options,
});
// Returns: { label: 'Red', value: 'red', hex: '#FF0000' }

// Multiple selection
const multiData = getSelectionsData({
  isMultiple: true,
  optionValue: 'value',
  selectedItem: '',
  selectedItems: ['red', 'blue'],
  modifiedOptions: options,
});
// Returns: [
//   { label: 'Red', value: 'red', hex: '#FF0000' },
//   { label: 'Blue', value: 'blue', hex: '#0000FF' }
// ]
```

--------------------------------

### Import Dropdown Types

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/INDEX.md

Import TypeScript types for DropdownProps and DropdownSelectHandle.

```typescript
import type { DropdownProps, DropdownSelectHandle } from 'react-native-input-select';
```

--------------------------------

### Import Custom Hooks

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/INDEX.md

Import custom hooks like useSearch and useSelectionHandler.

```typescript
import { useSearch, useSelectionHandler } from 'react-native-input-select';
```

--------------------------------

### Run Unit Tests

Source: https://github.com/azeezat/react-native-select/blob/main/CONTRIBUTING.md

Executes the unit test suite using Jest to ensure code correctness.

```sh
yarn test
```

--------------------------------

### Advanced Multi-Select Configuration

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/configuration.md

Set up a multi-select dropdown with search functionality, minimum/maximum selectable items, and custom controls for checkboxes, search input, list messages, and item removal.

```typescript
<DropdownSelect
  label="Select Team Members"
  placeholder="Choose members..."
  options={employees}
  optionLabel="name"
  optionValue="id"
  selectedValue={selectedEmployees}
  onValueChange={setSelectedEmployees}
  isMultiple
  isSearchable
  minSelectableItems={2}
  maxSelectableItems={5}
  primaryColor="blue"
  checkboxControls={{
    checkboxSize: 16,
    checkboxStyle: { backgroundColor: 'blue' },
    checkboxUnselectedColor: '#ddd',
  }}
  searchControls={{
    textInputProps: { placeholder: 'Search by name...' },
    searchCallback: (text) => analytics.track('searched', { text }),
  }}
  listControls={{
    selectAllText: 'Add Everyone',
    unselectAllText: 'Clear All',
    emptyListMessage: 'No employees found',
  }}
  selectedItemsControls={{
    showRemoveIcon: true,
    onRemoveItem: () => logChange('item_removed'),
  }}
/>
```

--------------------------------

### Lint Code with ESLint

Source: https://github.com/azeezat/react-native-select/blob/main/CONTRIBUTING.md

Runs ESLint to check for code style and potential errors.

```sh
yarn lint
```

--------------------------------

### Importing All Types with Namespace

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/MODULE-EXPORTS.md

Import all types from the library under a namespace for clear type referencing. This is useful for defining complex prop types.

```typescript
import type * as RNSelectTypes from 'react-native-input-select';

// Usage
const props: RNSelectTypes.DropdownProps = { /* ... */ };
const handle: RNSelectTypes.DropdownSelectHandle = { /* ... */ };
```

--------------------------------

### Import Utility Functions

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/INDEX.md

Import utility functions such as removeDisabledItems and isSectionList.

```typescript
import { removeDisabledItems, isSectionList } from 'react-native-input-select';
```

--------------------------------

### Modal with Ref Control for DropdownSelect

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/ref-handle.md

Shows how to integrate DropdownSelect within a modal and control its open/close state imperatively using a ref. This allows for more complex UI flows where the dropdown needs to be managed within a modal context.

```typescript
import React, { useRef, useState } from 'react';
import {
  View,
  Button,
  Modal,
  Text,
  StyleSheet,
} from 'react-native';
import DropdownSelect from 'react-native-input-select';
import type { DropdownSelectHandle } from 'react-native-input-select';

function ModalWithDropdown() {
  const dropdownRef = useRef<DropdownSelectHandle>(null);
  const [showModal, setShowModal] = useState(false);
  const [selected, setSelected] = useState<string>('');

  const handleOpen = () => {
    setShowModal(true);
    // Optionally open dropdown immediately
    setTimeout(() => dropdownRef.current?.open(), 100);
  };

  const handleSubmit = () => {
    dropdownRef.current?.close();
    setShowModal(false);
    console.log('Selected:', selected);
  };

  return (
    <View style={{ padding: 20 }}>
      <Button title="Open Modal" onPress={handleOpen} />

      <Modal visible={showModal} transparent>
        <View style={styles.overlay}>
          <View style={styles.container}>
            <Text style={styles.title}>Choose an Option</Text>

            <DropdownSelect
              ref={dropdownRef}
              label="Options"
              options={[
                { label: 'Option A', value: 'a' },
                { label: 'Option B', value: 'b' },
                { label: 'Option C', value: 'c' },
              ]}
              selectedValue={selected}
              onValueChange={setSelected}
            />

            <View style={styles.buttonRow}>
              <Button 
                title="Cancel" 
                onPress={() => {
                  dropdownRef.current?.close();
                  setShowModal(false);
                }}
              />
              <Button title="Submit" onPress={handleSubmit} />
            </View>
          </View>
        </View>
      </Modal>
    </View>
  );
}

const styles = StyleSheet.create({
  overlay: {
    flex: 1,
    backgroundColor: 'rgba(0, 0, 0, 0.5)',
    justifyContent: 'center',
  },
  container: {
    margin: 20,
    padding: 20,
    backgroundColor: 'white',
    borderRadius: 12,
  },
  title: {
    fontSize: 18,
    fontWeight: 'bold',
    marginBottom: 15,
  },
  buttonRow: {
    flexDirection: 'row',
    gap: 10,
    marginTop: 20,
  },
});

export default ModalWithDropdown;
```

--------------------------------

### DropdownSelect Component Hierarchy

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/components.md

Illustrates the nested structure of the main DropdownSelect component, showing its sub-components like Dropdown, CustomModal, and their children. Useful for understanding component relationships and customization points.

```plaintext
DropdownSelect (main exported component)
│
├─ Dropdown (input display)
│  └─ DropdownSelectedItemsContainer
│     └─ DropdownSelectedItem (for each selection)
│
├─ CustomModal (modal container)
│  └─ Input (search box - conditional)
│  └─ CheckBox (select all - conditional)
│  └─ DropdownFlatList OR DropdownSectionList
│     └─ DropdownListItem (for each option)
│        └─ CheckBox (with label)
│     └─ ItemSeparatorComponent (between items)
│     └─ ListEmptyComponent (when empty)
│
└─ [error/helper text display]
```

--------------------------------

### open()

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/ref-handle.md

Opens the dropdown modal programmatically. It respects the disabled prop and resets search and list state if the component is not disabled.

```APIDOC
## open()

### Description
Opens the dropdown modal programmatically.

### Method
open(): void

### Behavior
- Opens the modal if not already visible
- Respects the `disabled` prop (no-op if disabled)
- Resets search and list state
- Does nothing if component is disabled

### Example
```typescript
const dropdownRef = useRef<DropdownSelectHandle>(null);

<Button 
  title="Show Dropdown" 
  onPress={() => dropdownRef.current?.open()}
/>

<DropdownSelect
  ref={dropdownRef}
  options={options}
  selectedValue={selected}
  onValueChange={setSelected}
/>
```
```

--------------------------------

### Flat List Options Structure

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/README.md

Use a simple array of objects for flat lists. Each object should have 'label' and 'value' properties.

```typescript
const options = [
  { label: 'Item 1', value: 'item1' },
  { label: 'Item 2', value: 'item2' },
];
```

--------------------------------

### Advanced Hook Usage in Custom Component

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/hooks.md

Demonstrates the independent use of useSearch, useSelectionHandler, and useModal hooks for building custom dropdown components.

```typescript
import {
  useSearch,
  useSelectionHandler,
  useModal,
} from 'react-native-input-select';

function CustomDropdown() {
  const { searchValue, setSearchValue, filteredOptions } = useSearch({
    initialOptions,
    optionLabel: 'label',
    optionValue: 'value',
    searchCallback: () => {},
  });

  const { selectedItems, handleMultipleSelections } = useSelectionHandler({
    initialSelectedValue: [],
    isMultiple: true,
    onValueChange: console.log,
    closeModal: () => {},
    autoCloseOnSelect: false,
  });

  const { isVisible, openModal, closeModal } = useModal({
    resetOptionsRelatedState: () => {
      setSearchValue('');
    },
    disabled: false,
  });

  // Custom rendering with hooks...
}

```

--------------------------------

### Section List Options Structure

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/README.md

Organize options into groups using a section list structure. Each section has a 'title' and 'data' array containing items.

```typescript
const options = [
  {
    title: 'Group A',
    data: [
      { label: 'Item 1', value: 'item1' },
      { label: 'Item 2', value: 'item2' },
    ],
  },
  {
    title: 'Group B',
    data: [
      { label: 'Item 3', value: 'item3' },
    ],
  },
];
```

--------------------------------

### Form with Validation using DropdownSelect

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/api-reference/ref-handle.md

Demonstrates how to implement form validation with DropdownSelect. It includes custom validation logic, error message display, and programmatic opening of invalid fields.

```typescript
import React, { useRef, useState } from 'react';
import { View, Button, Text, Alert } from 'react-native';
import DropdownSelect from 'react-native-input-select';
import type { DropdownSelectHandle } from 'react-native-input-select';

function FormWithValidation() {
  const countryRef = useRef<DropdownSelectHandle>(null);
  const stateRef = useRef<DropdownSelectHandle>(null);
  
  const [country, setCountry] = useState<string>('');
  const [state, setState] = useState<string>('');
  const [errors, setErrors] = useState<Record<string, string>>({});

  const validateForm = () => {
    const newErrors: Record<string, string> = {};

    if (!country) {
      newErrors.country = 'Country is required';
    }
    if (!state) {
      newErrors.state = 'State is required';
    }

    setErrors(newErrors);
    return Object.keys(newErrors).length === 0;
  };

  const handleSubmit = () => {
    if (validateForm()) {
      Alert.alert('Success', `Country: ${country}, State: ${state}`);
    } else {
      // Open first invalid field
      if (errors.country) {
        countryRef.current?.open();
      } else if (errors.state) {
        stateRef.current?.open();
      }
    }
  };

  return (
    <View style={{ padding: 20 }}>
      <DropdownSelect
        ref={countryRef}
        label="Country"
        placeholder="Select country..."
        options={[
          { label: 'USA', value: 'us' },
          { label: 'Canada', value: 'ca' },
          { label: 'Mexico', value: 'mx' },
        ]}
        selectedValue={country}
        onValueChange={(val) => {
          setCountry(val);
          setErrors((prev) => {
            const updated = { ...prev };
            delete updated.country;
            return updated;
          });
        }}
        error={errors.country}
        primaryColor="blue"
      />

      {country && (
        <DropdownSelect
          ref={stateRef}
          label="State/Province"
          placeholder="Select state..."
          options={getStatesByCountry(country)}
          selectedValue={state}
          onValueChange={(val) => {
            setState(val);
            setErrors((prev) => {
              const updated = { ...prev };
              delete updated.state;
              return updated;
            });
          }}
          error={errors.state}
          primaryColor="blue"
        />
      )}

      <Button 
        title="Submit" 
        onPress={handleSubmit}
        color="blue"
      />
    </View>
  );
}

function getStatesByCountry(country: string) {
  const states: Record<string, any[]> = {
    us: [
      { label: 'California', value: 'ca' },
      { label: 'Texas', value: 'tx' },
      { label: 'New York', value: 'ny' },
    ],
    ca: [
      { label: 'Ontario', value: 'on' },
      { label: 'Quebec', value: 'qc' },
      { label: 'British Columbia', value: 'bc' },
    ],
    mx: [
      { label: 'Mexico City', value: 'mx' },
      { label: 'Jalisco', value: 'jal' },
      { label: 'Veracruz', value: 'ver' },
    ],
  };
  return states[country] || [];
}

export default FormWithValidation;

```

--------------------------------

### Importing Component and Specific Types

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/MODULE-EXPORTS.md

Import the main `DropdownSelect` component along with specific types like `DropdownProps`. This allows direct component usage and type checking.

```typescript
import DropdownSelect, { type DropdownProps } from 'react-native-input-select';

<DropdownSelect
  label="Select"
  options={[]}
  selectedValue=""
  onValueChange={() => {}} 
/>
```

--------------------------------

### Importing Specific Components and Types

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/MODULE-EXPORTS.md

Import only the necessary components and types directly from the library's main export. Use named imports for utilities to improve code clarity and tree-shaking.

```typescript
// Import only what you need
import DropdownSelect from 'react-native-input-select';
import type { DropdownProps } from 'react-native-input-select';

// Use named imports for utilities
import { removeDisabledItems } from 'react-native-input-select';

// Memoize types if needed
type MyDropdownProps = DropdownProps & { customProp?: string };
```

--------------------------------

### Import Named Utility Functions

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/MODULE-EXPORTS.md

Import helper functions for common operations such as data retrieval, item filtering, type checking, property extraction, regex escaping, array comparison, and style property filtering.

```typescript
import {
  getSelectionsData,
  removeDisabledItems,
  isSectionList,
  extractPropertyFromArray,
  escapeRegExp,
  shallowArrayEqual,
  extractTextStylesFromArray,
} from 'react-native-input-select';
```

--------------------------------

### Import All Type Definitions

Source: https://github.com/azeezat/react-native-select/blob/main/_autodocs/MODULE-EXPORTS.md

Import all available type definitions from the package to enhance type safety in your project. These types define the props and structures for various components and functionalities.

```typescript
import type {
  DropdownProps,
  CommonDropdownProps,
  TDropdownInputProps,
  TCheckboxControls,
  TCustomModalControls,
  TListProps,
  TListControls,
  TSelectedItemsControls,
  DropdownSelectHandle,
  TSelectedItem,
  TSelectedItemWithReactComponent,
  TFlatList,
  TFlatListItem,
  TSectionList,
  TSectionListItem,
  CheckboxProps,
} from 'react-native-input-select';
```