React Native Infinite Picker 🎰🤏⏰

A performant, flexible, infinite-scroll picker component for React Native apps 🔥

Great for any kind of select input, such as timers, alarms, duration inputs or date inputs.

Works with Expo and bare React Native apps ✅

Includes haptic and audio feedback for a native feel 🚀

• Demos 📱
• Peer Dependencies 👶
  • Linear Gradient
  • Haptic Feedback
  • Audio Feedback (Click Sound)
• Installation 🚀
• Examples 😎
  • Timer Picker Modal (Dark Mode) 🌚
  • Timer Picker Modal (Light Mode) 🌞
  • Timer Picker with Transparent Fade-Out (Dark Mode) 🌒
  • Timer Picker with Customisation (Light Mode) 🌔
• Props 💅
  • TimerPicker ⏲️
    • Custom Styles 👗
    • Performance
    • Custom FlatList
    • Generic feedback
  • TimerPickerModal ⏰
    • Custom Styles 👕
• Methods 🔄
  • TimerPicker
  • TimerPickerModal
• Contributing 🧑‍🤝‍🧑
  • Dev Setup
  • GitHub Guidelines
• Limitations ⚠
• License 📝

Demos 📱

Try it out for yourself on Expo Snack! Make sure to run it on a mobile to see it working properly.

Peer Dependencies 👶

This component will work in your React Native Project without any peer dependencies. However, to enable certain additional features (e.g. fade-out, feedback) you will need to supply various libraries as props. These are detailed below.

Linear Gradient

If you want the numbers to fade in/out at the top and bottom of the picker, you will need to install either:

• expo-linear-gradient (if using Expo)
• react-native-linear-gradient (if using in a bare React Native project)

To enable the linear gradient, you need to supply the component as a prop to either TimerPickerModal or TimerPicker.

Masked View

To make the numbers fade in/out on a transparent background (e.g. if the picker is rendered on top of a gradient or image), you will need to install the @react-native-masked-view/masked-view component. This is as the standard LinearGradient implementation relies on there being a solid background colour. You then just need to set backgroundColor: "transparent on the TimerPicker styles prop.

import MaskedView from "@react-native-masked-view/masked-view";

To enable the fade-out on a transparent background, you need to supply the imported MaskedView component AND one of the LinearGradient components as props to either TimerPickerModal or TimerPicker. (see this example)

Haptic Feedback

Enable haptic feedback with the expo-haptics module:

import * as Haptics from "expo-haptics";

To enable haptic feedback, you need to supply the imported Haptics namespace as a prop to either TimerPickerModal or TimerPicker.

Generic feedback support is possible with the pickerFeeback prop.

Audio Feedback (Click Sound)

Enable audio feedback with the expo-av module:

import { Audio } from "expo-av";

To enable audio feedback, you need to supply the imported Audio class as a prop to either TimerPickerModal or TimerPicker.

Please note that the default click sound uses a hosted mp3 file. To make the click sound work offline, you need to supply your own sound asset through the clickSoundAsset prop. You can download the default click sound here.

Generic feedback support is possible with the pickerFeeback prop.

Installation 🚀

Supports React Native >= 0.59.0 and React >= 16.8.0.

Just run:

1npm install react-native-infinite-picker

or

1yarn add react-native-infinite-picker

Examples 😎

Timer Picker Modal (Dark Mode) 🌚

1import { TimerPickerModal } from "react-native-infinite-picker";
2import { LinearGradient } from "expo-linear-gradient"; // or `import LinearGradient from "react-native-linear-gradient"`
3import { Audio } from "expo-av"; // for audio feedback (click sound as you scroll)
4import * as Haptics from "expo-haptics"; // for haptic feedback
5
6....
7const [showPicker, setShowPicker] = useState(false);
8const [alarmString, setAlarmString] = useState<
9        string | null
10    >(null);
11
12const formatTime = ({
13    hours,
14    minutes,
15    seconds,
16}: {
17    hours?: number;
18    minutes?: number;
19    seconds?: number;
20}) => {
21    const timeParts = [];
22
23    if (hours !== undefined) {
24        timeParts.push(hours.toString().padStart(2, "0"));
25    }
26    if (minutes !== undefined) {
27        timeParts.push(minutes.toString().padStart(2, "0"));
28    }
29    if (seconds !== undefined) {
30        timeParts.push(seconds.toString().padStart(2, "0"));
31    }
32
33    return timeParts.join(":");
34};
35
36return (
37    <View style={{backgroundColor: "#514242", alignItems: "center", justifyContent: "center"}}>
38        <Text style={{fontSize: 18, color: "#F1F1F1"}}>
39            {alarmStringExample !== null
40                ? "Alarm set for"
41                : "No alarm set"}
42        </Text>
43        <TouchableOpacity
44            activeOpacity={0.7}
45            onPress={() => setShowPicker(true)}>
46            <View style={{alignItems: "center"}}>
47                {alarmString !== null ? (
48                    <Text style={{color: "#F1F1F1", fontSize: 48}}>
49                        {alarmString}
50                    </Text>
51                ) : null}
52                <TouchableOpacity
53                    activeOpacity={0.7}
54                    onPress={() => setShowPicker(true)}>
55                    <View style={{marginTop: 30}}>
56                        <Text
57                            style={{
58                                paddingVertical: 10,
59                                paddingHorizontal: 18,
60                                borderWidth: 1,
61                                borderRadius: 10,
62                                fontSize: 16,
63                                overflow: "hidden",
64                                borderColor: "#C2C2C2",
65                                color: "#C2C2C2"
66                                }}>
67                            {"Set Alarm 🔔"}
68                        </Text>
69                    </View>
70                </TouchableOpacity>
71            </View>
72        </TouchableOpacity>
73        <TimerPickerModal
74            visible={showPicker}
75            setIsVisible={setShowPicker}
76            onConfirm={(pickedDuration) => {
77                setAlarmString(formatTime(pickedDuration));
78                setShowPicker(false);
79            }}
80            modalTitle="Set Alarm"
81            onCancel={() => setShowPicker(false)}
82            closeOnOverlayPress
83            Audio={Audio}
84            LinearGradient={LinearGradient}
85            Haptics={Haptics}
86            styles={{
87                theme: "dark",
88            }}
89            modalProps={{
90                overlayOpacity: 0.2,
91            }}
92        />
93    </View>
94)
95

Timer Picker Modal (Light Mode) 🌞

1import { TimerPickerModal } from "react-native-infinite-picker";
2import { LinearGradient } from "expo-linear-gradient"; // or `import LinearGradient from "react-native-linear-gradient"`
3import { Audio } from "expo-av"; // for audio feedback (click sound as you scroll)
4import * as Haptics from "expo-haptics"; // for haptic feedback
5
6....
7const [showPicker, setShowPicker] = useState(false);
8const [alarmString, setAlarmString] = useState<
9        string | null
10    >(null);
11
12const formatTime = ({
13    hours,
14    minutes,
15    seconds,
16}: {
17    hours?: number;
18    minutes?: number;
19    seconds?: number;
20}) => {
21    const timeParts = [];
22
23    if (hours !== undefined) {
24        timeParts.push(hours.toString().padStart(2, "0"));
25    }
26    if (minutes !== undefined) {
27        timeParts.push(minutes.toString().padStart(2, "0"));
28    }
29    if (seconds !== undefined) {
30        timeParts.push(seconds.toString().padStart(2, "0"));
31    }
32
33    return timeParts.join(":");
34};
35
36return (
37    <View style={{backgroundColor: "#F1F1F1", alignItems: "center", justifyContent: "center"}}>
38        <Text style={{fontSize: 18, color: "#202020"}}>
39            {alarmStringExample !== null
40                ? "Alarm set for"
41                : "No alarm set"}
42        </Text>
43        <TouchableOpacity
44            activeOpacity={0.7}
45            onPress={() => setShowPicker(true)}>
46            <View style={{alignItems: "center"}}>
47                {alarmString !== null ? (
48                    <Text style={{color: "#202020", fontSize: 48}}>
49                        {alarmString}
50                    </Text>
51                ) : null}
52                <TouchableOpacity
53                    activeOpacity={0.7}
54                    onPress={() => setShowPicker(true)}>
55                    <View style={{marginTop: 30}}>
56                        <Text
57                            style={{paddingVertical: 10,
58                            paddingHorizontal: 18,
59                            borderWidth: 1,
60                            borderRadius: 10,
61                            fontSize: 16,
62                            overflow: "hidden",
63                            borderColor: "#8C8C8C",
64                            color: "#8C8C8C"
65                            }}>
66                            Set Alarm 🔔
67                        </Text>
68                    </View>
69                </TouchableOpacity>
70            </View>
71        </TouchableOpacity>
72        <TimerPickerModal
73            visible={showPicker}
74            setIsVisible={setShowPicker}
75            onConfirm={(pickedDuration) => {
76                setAlarmString(formatTime(pickedDuration));
77                setShowPicker(false);
78            }}
79            modalTitle="Set Alarm"
80            onCancel={() => setShowPicker(false)}
81            closeOnOverlayPress
82            use12HourPicker
83            Audio={Audio}
84            // supply your own custom click sound asset
85            clickSoundAsset={require("./assets/custom_click.mp3")}
86            LinearGradient={LinearGradient}
87            Haptics={Haptics}
88            styles={{
89                theme: "light",
90            }}
91        />
92    </View>
93)
94

Timer Picker with Transparent Fade-Out (Dark Mode) 🌒

1import { TimerPicker } from "react-native-infinite-picker";
2import MaskedView from "@react-native-masked-view/masked-view"; // for transparent fade-out
3import { LinearGradient } from "expo-linear-gradient"; // or `import LinearGradient from "react-native-linear-gradient"`
4import { Audio } from "expo-av"; // for audio feedback (click sound as you scroll)
5import * as Haptics from "expo-haptics"; // for haptic feedback
6
7....
8const [showPicker, setShowPicker] = useState(false);
9const [alarmString, setAlarmString] = useState<
10        string | null
11    >(null);
12
13return (
14    <LinearGradient
15        colors={["#202020", "#220578"]}
16        start={{ x: 0, y: 0 }}
17        end={{ x: 1, y: 1 }}
18        style={{alignItems: "center", justifyContent: "center"}}>
19        <TimerPicker
20            padWithNItems={2}
21            hourLabel=":"
22            minuteLabel=":"
23            secondLabel=""
24            Audio={Audio}
25            LinearGradient={LinearGradient}
26            Haptics={Haptics}
27            MaskedView={MaskedView}
28            styles={{
29                theme: "dark",
30                backgroundColor: "transparent", // transparent fade-out
31                pickerItem: {
32                    fontSize: 34,
33                },
34                pickerLabel: {
35                    fontSize: 32,
36                    marginTop: 0,
37                },
38                pickerContainer: {
39                    marginRight: 6,
40                },
41                pickerItemContainer: {
42                    width: 100
43                },
44                pickerLabelContainer: {
45                    right: -20,
46                    top: 0,
47                    bottom: 6,
48                    width: 40,
49                    alignItems: "center",
50                },
51            }}
52        />
53    </LinearGradient>
54)
55

Timer Picker with Customisation (Light Mode) 🌔

1import { TimerPicker } from "react-native-infinite-picker";
2import { LinearGradient } from "expo-linear-gradient"; // or `import LinearGradient from "react-native-linear-gradient"`
3import { Audio } from "expo-av"; // for audio feedback (click sound as you scroll)
4import * as Haptics from "expo-haptics"; // for haptic feedback
5
6....
7const [showPicker, setShowPicker] = useState(false);
8const [alarmString, setAlarmString] = useState<
9        string | null
10    >(null);
11
12return (
13    <View style={{backgroundColor: "#F1F1F1", alignItems: "center", justifyContent: "center"}}>
14        <TimerPicker
15            padWithNItems={3}
16            hideHours
17            minuteLabel="min"
18            secondLabel="sec"
19            Audio={Audio}
20            LinearGradient={LinearGradient}
21            Haptics={Haptics}
22            styles={{
23                theme: "light",
24                pickerItem: {
25                    fontSize: 34,
26                },
27                pickerLabel: {
28                    fontSize: 26,
29                    right: -20,
30                },
31                pickerLabelContainer: {
32                    width: 60,
33                },
34                pickerItemContainer: {
35                    width: 150,
36                },
37            }}
38        />
39    </View>
40)
41

Props 💅

TimerPicker ⏲️

Prop	Description	Type	Default	Required
onDurationChange	Callback when the duration changes	(duration: { hours: number, minutes: number, seconds: number }) => void	-	false
initialValue	Initial value for the picker	{ hours?: number, minutes?: number, seconds?: number }	-	false
hideHours	Hide the hours picker	Boolean	false	false
hideMinutes	Hide the minutes picker	Boolean	false	false
hideSeconds	Hide the seconds picker	Boolean	false	false
hoursPickerIsDisabled	Disable the hours picker picker	Boolean	false	false
minutesPickerIsDisabled	Disable the minutes picker picker	Boolean	false	false
secondsPickerIsDisabled	Disable the seconds picker picker	Boolean	false	false
hourLimit	Limit on the hours it is possible to select	{ max?: Number, min?: Number }	-	false
minuteLimit	Limit on the minutes it is possible to select	{ max?: Number, min?: Number }	-	false
secondLimit	Limit on the seconds it is possible to select	{ max?: Number, min?: Number }	-	false
maximumHours	The highest value on the hours picker	Number	23	false
maximumMinutes	The highest value on the minutes picker	Number	59	false
maximumSeconds	The highest value on the seconds picker	Number	59	false
hourInterval	The interval between values on the hours picker	Number	1	false
minuteInterval	The interval between values on the minutes picker	Number	1	false
secondInterval	The interval between values on the seconds picker	Number	1	false
hourLabel	Label for the hours picker	String | React.ReactElement	h	false
minuteLabel	Label for the minutes picker	String | React.ReactElement	m	false
secondLabel	Label for the seconds picker	String | React.ReactElement	s	false
padHoursWithZero	Pad single-digit hours in the picker with a zero	Boolean	false	false
padMinutesWithZero	Pad single-digit minutes in the picker with a zero	Boolean	true	false
padSecondsWithZero	Pad single-digit seconds in the picker with a zero	Boolean	true	false
padWithNItems	Number of items to pad the picker with on either side	Number	1	false
aggressivelyGetLatestDuration	Set to True to ask DurationScroll to aggressively update the latestDuration ref	Boolean	false	false
allowFontScaling	Allow font in the picker to scale with accessibility settings	Boolean	false	false
use12HourPicker	Switch the hour picker to 12-hour format with an AM / PM label	Boolean	false	false
amLabel	Set the AM label if using the 12-hour picker	String	am	false
pmLabel	Set the PM label if using the 12-hour picker	String	pm	false
repeatHourNumbersNTimes	Set the number of times the list of hours is repeated in the picker	Number	7	false
repeatMinuteNumbersNTimes	Set the number of times the list of minutes is repeated in the picker	Number	3	false
repeatSecondNumbersNTimes	Set the number of times the list of seconds is repeated in the picker	Number	3	false
disableInfiniteScroll	Disable the infinite scroll feature	Boolean	false	false
LinearGradient	Linear Gradient Component (required for picker fade-out)	expo-linear-gradient.LinearGradient or react-native-linear-gradient.default	-	false
MaskedView	Masked View Component (required for picker fade-out on transparent background)	@react-native-masked-view/masked-view.default	-	false
Haptics	Haptics Namespace (required for Haptic feedback)	expo-haptics	-	false
Audio	Audio Class (required for audio feedback i.e. click sound)	expo-av.Audio	-	false
pickerFeedback	Generic picker feedback as alternative to the above Expo feedback support	() => void | Promise<void>	-	false
FlatList	FlatList component used internally to implement each picker (hour, minutes and seconds). More info below	react-native.FlatList	FlatList from react-native	false
clickSoundAsset	Custom sound asset for click sound (required for offline click sound - download default here)	require(.../somefolderpath) or {uri: www.someurl}	-	false
pickerContainerProps	Props for the picker container	React.ComponentProps<typeof View>	-	false
pickerGradientOverlayProps	Props for the gradient overlay (supply a different locations array to adjust its position) overlays	Partial<LinearGradientProps>	-	false
styles	Custom styles for the timer picker	CustomTimerPickerStyles	-	false

Custom Styles 👗

The following custom styles can be supplied to re-style the component in any way. Various styles are applied by default - you can take a look at these here.

Style Prop	Description	Type
theme	Theme of the component	"light" | "dark"
backgroundColor	Main background color	string
text	Base text style	TextStyle
pickerContainer	Main container for the picker	ViewStyle & { backgroundColor?: string }
pickerLabelContainer	Container for the picker's labels	ViewStyle
pickerLabel	Style for the picker's labels	TextStyle
pickerAmPmContainer	Style for the picker's labels	ViewStyle
pickerAmPmLabel	Style for the picker's labels	TextStyle
pickerItemContainer	Container for each number in the picker	ViewStyle & { height?: number }
pickerItem	Style for each individual picker number	TextStyle
disabledPickerItem	Style for any numbers outside any set limits	TextStyle
disabledPickerContainer	Style for disabled pickers	ViewStyle
pickerGradientOverlay	Style for the gradient overlay (fade out)	ViewStyle
durationScrollFlatList	Style for the Flatlist in each picker	ViewStyle
durationScrollFlatListContainer	Style for the View that contains the Flatlist in each picker	ViewStyle
durationScrollFlatListContentContainer	Style for the Flatlist's contentContainerStyle prop in each picker	ViewStyle

Note the minor limitations to the allowed styles for pickerContainer and pickerItemContainer. These are made because these styles are used for internal calculations and all possible backgroundColor/height types are not supported.

Performance

When the disableInfiniteScroll prop is not set, the picker gives the appearance of an infinitely scrolling picker by auto-scrolling forward/back when you near the start/end of the list. When the picker auto-scrolls, a momentary flicker is visible if you are scrolling very slowly.

To mitigate for this, the list of numbers in each picker is repeated a given number of times based on the length of the list (8 times for the hours picker, and 3 times for the minutes and seconds picker). These have a performance trade-off: higher values mean the picker has to auto-scroll less to maintain the infinite scroll, but has to render a longer list of numbers. The number of repetitions automatically adjusts if the number of items in the picker changes (e.g. if an interval is included, or the maximum value is modified), balancing the trade-off. You can also manually adjust the number of repetitions in each picker with the repeatHourNumbersNTimes, repeatMinuteNumbersNTimes and repeatSecondNumbersNTimes props.

Note that you can avoid the auto-scroll flickering entirely by disabling infinite scroll. You could then set the above props to high values, so that a user has to scroll far down/up the list to reach the end of the list.

Custom FlatList

The library offers the ability to provide a custom component for the <FlatList />, instead of the default React Native component. This allows for more flexibility and integration with libraries like react-native-gesture-handler or other components built on top of it, like https://ui.gorhom.dev/components/bottom-sheet.

E.g. if you want to place the timer picker within that bottom-sheet component, the scrolling detection from the bottom-sheet would interfere with the one inside the timer picker, but it can be easily solved by providing the FlatList component from react-native-gesture-handler like this:

1import { FlatList } from 'react-native-gesture-handler';
2import { TimerPicker } from "react-native-infinite-picker";
3
4// ...
5
6<TimerPicker
7    {...props}
8    FlatList={FlatList}
9/>
10

Please note that this solution does not work for all bottom-sheet components (e.g. @tamagui/sheet) as it depends on the implementation of each component.

Important: The custom component needs to have the same interface as React Native's <FlatList /> in order for it to work as expected. A complete reference of the current usage can be found here.

Generic feedback

To enable haptic feedback from the non-Expo module react-native-haptic-feedback (or provide feedback in any other form) you can use the generic feedback callback prop pickerFeedback. This function is called whenever any of the pickers tick onto a new number.

1import { trigger } from 'react-native-haptic-feedback';
2import { TimerPicker } from "react-native-infinite-picker";
3
4// ...
5
6<TimerPicker
7    {...props}
8    pickerFeedback={() => trigger('impactLight')}
9/>
10

TimerPickerModal ⏰

The TimerPickerModal component accepts all TimerPicker props, and the below additional props.

Prop	Description	Type	Default	Required
visible	Determines if the modal is visible	Boolean	-	true
setIsVisible	Callback to set modal visibility	(isVisible: boolean) => void	-	true
onConfirm	Callback when the user confirms the selected time	({ hours, minutes, seconds }: { hours: number, minutes: number, seconds: number }) => void	-	true
onCancel	Callback when the user cancels the selection	() => void	-	false
closeOnOverlayPress	Determines if the modal should close on overlay press	Boolean	false	false
hideCancelButton	Hide the cancel button within the modal	Boolean	false	false
confirmButtonText	Text for the confirm button	String	Confirm	false
cancelButtonText	Text for the cancel button	String	Cancel	false
modalTitle	Title text for the modal	String	-	false
modalProps	Props for the main modal component	React.ComponentProps<typeof Modal>	-	false
containerProps	Props for the main container	React.ComponentProps<typeof View>	-	false
contentContainerProps	Props for the content container	React.ComponentProps<typeof View>	-	false
buttonContainerProps	Props for the button containers	React.ComponentProps<typeof View>	-	false
buttonTouchableOpacityProps	Props for the button touchable opacities	React.ComponentProps<typeof TouchableOpacity>	-	false
modalTitleProps	Props for the modal title text component	React.ComponentProps<typeof Text>	-	false
styles	Custom styles for the timer picker modal	CustomTimerPickerModalStyles	-	false

Custom Styles 👕

The following custom styles can be supplied to re-style the component in any way. You can also supply all of the styles specified in CustomTimerPickerStyles. Various styles are applied by default - you can take a look at these here.

Style Prop	Description	Type
container	Main container's style	ViewStyle
contentContainer	Style for the content's container	ViewStyle
buttonContainer	Style for the container around the buttons	ViewStyle
button	General style for both buttons	TextStyle
cancelButton	Style for the cancel button	TextStyle
confirmButton	Style for the confirm button	TextStyle
modalTitle	Style for the title of the modal	TextStyle

Methods 🔄

TimerPicker

The library exposes a TimerPickerRef type, which can be used to type your ref to the picker:

1const timerPickerRef = useRef < TimerPickerRef > null;

It has the following available methods:

reset - imperative method to reset the selected duration to their initial values.

1timerPickerRef.current.reset(options?: { animated: boolean });

setValue - imperative method to set the selected duration to a particular value

1timerPickerRef.current.setValue({ hours: number, minutes: number, seconds: number }, options?: { animated: boolean });

It also exposes the following ref object:

latestDuration - provides access to the latest duration (even during scrolls). This only works if aggressivelyGetLatestDuration is set to True (as in TimerPickerModal). It is used internally to ensure that the latest duration is returned in TimerPickerModal on pressing the confirm button, even if the inputs are still scrolling.

1const latestDuration = timerPickerRef.current?.latestDuration;
2const newDuration = {
3    hours: latestDuration?.hours?.current,
4    minutes: latestDuration?.minutes?.current,
5    seconds: latestDuration?.seconds?.current,
6};

TimerPickerModal

An identical ref is also exposed for the TimerPickerModal component.

Contributing 🧑‍🤝‍🧑

Contributions to this project are more than welcome.

Dev Setup

To get this project running locally:

1. Clone the Git repo.
2. Run yarn setup from the project root (this installs the project dependencies and the examples' additional dependencies)

You can then start either the Expo example or the bare React Native example:

• For Expo, run yarn start to start the Expo example in Expo Go.
• For bare React Native, run yarn start-bare:android or start-bare:ios to start the project on an emulator/device.

GitHub Guidelines

There are two permenant branches: main and develop. You should never work directly on either of these branches.

1. Create a new branch off develop for your work using the pattern feature/{DESCRIPTION}.
2. When you think your work is ready for review, submit a PR from your branch back to develop.
3. Once the PR is resolved, your work will be merged into develop, and will be included in the next major/minor release.

Limitations ⚠

The project is not compatibile with React Native versions prior to v0.72.0 due to this React Native issue.

License 📝

This project is licensed under the MIT License.