react-ios-style-picker

react-ios-style-picker is a highly customizable, easy-to-use React component library designed to mimic the native iOS picker interface. This library provides an accessible way to integrate picker functionality into your React applications. The components are built with flexibility in mind, allowing for extensive customization in terms of appearance and behavior.

The library includes two main components:

• Picker: Enables users to select options from a scrollable list, which can be customized with various styles and callback functions.
• BottomSheet: A versatile component that slides up from the bottom of the screen, perfect for housing pickers, menus, or other content in a modal overlay.

Whether you're building a mobile-first design or adding mobile-friendly elements to a responsive web application, react-ios-style-picker provides the tools you need to incorporate sleek, intuitive selection interfaces.

Key Features

• iOS-like Interface: Provides a user experience similar to the native iOS picker, making it ideal for creating consistent and familiar interfaces across web and mobile platforms.
• Customizable Appearance: Offers extensive styling options to match the picker and bottom sheet components with your application's theme.
• Flexible Functionality: Supports a variety of use cases from simple date pickers to more complex custom selector interfaces.
• Accessibility Focused: Designed with accessibility in mind with ARIA attributes and keyboard support.
• TypeScript Support: Fully typed with TypeScript for better development experience.
• Tree-shakeable: Optimized for modern bundlers with proper side effects configuration.

Installation

To use these components in your project, you need to install the library via npm or yarn:

npm install react-ios-style-picker

or

yarn add react-ios-style-picker

Usage

Picker

The Picker component allows users to select an item from a scrollable list. It is customizable with styles and callback functions.

Props

Prop	Type	Default	Description
list	(string | number)[]	required	Array of items to display in the picker
itemHeight	number	50	Height of each item in pixels
initialSelected	string | number	-	Initially selected item
onSelectedChange	(selected: string | number) => void	-	Callback function called when a new item is selected
itemClassName	string	-	Additional CSS class for each item
itemStyle	React.CSSProperties	-	Inline styles for each item
className	string	-	CSS class for the wrapper div
style	React.CSSProperties	-	Inline styles for the wrapper div
listClassName	string	-	CSS class for the list element
listStyle	React.CSSProperties	-	Inline styles for the list element
showGradientMask	boolean	true	Show gradient mask at top and bottom
showCenterIndicator	boolean	true	Show center selection indicator
theme	"light" | "dark" | "auto"	"auto"	Theme mode

Basic Example

import { Picker } from "react-ios-style-picker";

function App() {
  const [selected, setSelected] = React.useState("Option 2");

  return (
    <Picker
      list={["Option 1", "Option 2", "Option 3"]}
      itemHeight={40}
      initialSelected={selected}
      onSelectedChange={(value) => {
        console.log(`Selected: ${value}`);
        setSelected(value);
      }}
    />
  );
}

TypeScript Example

import { Picker, ScrollPickerProps } from "react-ios-style-picker";

function App() {
  const options: ScrollPickerProps['list'] = ["Apple", "Banana", "Cherry"];
  const [selected, setSelected] = React.useState<string | number>("Banana");

  return (
    <Picker
      list={options}
      itemHeight={50}
      initialSelected={selected}
      onSelectedChange={setSelected}
      theme="dark"
      showGradientMask={true}
      showCenterIndicator={true}
    />
  );
}

Advanced Styling Example

import { Picker } from "react-ios-style-picker";

function StyledPicker() {
  return (
    <Picker
      list={Array.from({ length: 100 }, (_, i) => i + 1)}
      itemHeight={60}
      className="my-picker-wrapper"
      listClassName="my-custom-list"
      itemClassName="my-custom-item"
      itemStyle={{
        fontSize: "18px",
        fontWeight: "500",
        color: "#333",
      }}
      style={{
        width: "200px",
        margin: "0 auto",
      }}
    />
  );
}

BottomSheet

The BottomSheet component is used to display content in a sliding panel from the bottom. It is ideal for modal views.

Props

Prop	Type	Default	Description
children	React.ReactNode | React.ReactNode[]	required	Content to display inside the BottomSheet
isOpen	boolean	required	Whether the BottomSheet is visible
onClose	() => void	required	Function to call when the BottomSheet needs to be closed
className	string	""	Additional CSS class for the overlay
style	React.CSSProperties	{}	Inline styles for the BottomSheet content
button	React.ReactNode	-	Optional button to display in the BottomSheet
theme	"light" | "dark" | "auto"	"auto"	Theme mode

Basic Example

import { BottomSheet } from "react-ios-style-picker";

function App() {
  const [isOpen, setIsOpen] = React.useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Open BottomSheet</button>
      <BottomSheet
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
      >
        <div>Content goes here</div>
      </BottomSheet>
    </>
  );
}

TypeScript Example

import { BottomSheet, BottomSheetProps } from "react-ios-style-picker";

function App() {
  const [isOpen, setIsOpen] = React.useState<boolean>(false);

  const handleClose: BottomSheetProps['onClose'] = () => {
    setIsOpen(false);
  };

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Open BottomSheet</button>
      <BottomSheet
        isOpen={isOpen}
        onClose={handleClose}
        theme="light"
      >
        <h2>Title</h2>
        <p>Your content here</p>
      </BottomSheet>
    </>
  );
}

Combined Example with Picker

import { Picker, BottomSheet } from "react-ios-style-picker";

function DatePickerSheet() {
  const [isOpen, setIsOpen] = React.useState(false);
  const [selectedYear, setSelectedYear] = React.useState(2024);

  const years = Array.from({ length: 50 }, (_, i) => 2000 + i);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>
        Select Year: {selectedYear}
      </button>
      
      <BottomSheet
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        button={
          <button onClick={() => setIsOpen(false)}>Done</button>
        }
      >
        <Picker
          list={years}
          initialSelected={selectedYear}
          onSelectedChange={setSelectedYear}
          itemHeight={50}
        />
      </BottomSheet>
    </>
  );
}

Accessibility

The components are built with accessibility in mind:

• Picker: Includes ARIA attributes (role="listbox", aria-label, aria-activedescendant) for screen readers
• BottomSheet:
  • Supports ESC key to close
  • Includes role="dialog" and aria-modal="true"
  • Manages focus automatically

Styling

The library includes default CSS styles that are automatically imported. The CSS is modular and can be customized using:

1. CSS Classes: Add custom classes via className, listClassName, itemClassName props
2. Inline Styles: Use style, listStyle, itemStyle props
3. Theme Mode: Use theme prop to switch between light/dark modes
4. CSS Variables: Override CSS custom properties in your own stylesheet

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

License

MIT © reeseo3o

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Issues

If you find a bug or have a feature request, please file an issue at GitHub Issues.