TimePick Kit React

A flexible and customizable time picker component for React applications with built-in popover support.

Features

🎨 Fully customizable styling via Tailwind CSS
🔄 Smooth animations with Framer Motion
⌨️ Keyboard navigation support
🎯 Click outside detection
🌗 Light/Dark mode support
📱 Mobile-friendly design
⚡ Lightweight and performant
🔌 Easy integration

Installation

npm install timepick-kit-react

Required Peer Dependencies

The following packages are required as peer dependencies:

{
  "react": "^16.8.0 || ^17.0.0 || ^18.0.0",
  "date-fns": "^2.30.0",
  "framer-motion": "^10.12.16",
  "lucide-react": "^0.244.0",
  "clsx": "^1.2.1",
  "tailwind-merge": "^1.12.0"
}

Basic Usage

import { useState } from "react";
import {
  Popover,
  PopoverTrigger,
  PopoverContent,
  PopoverButton,
  TimePicker,
  TimeInput,
} from "timepick-kit-react";
import "timepick-kit-react/index.css";

function App() {
  const [time, setTime] = useState<TimeInput>(new Date());

  return (
    <Popover>
      <PopoverTrigger>
        <PopoverButton time={time} />
      </PopoverTrigger>
      <PopoverContent>
        <TimePicker value={time} onChange={(newTime) => setTime(newTime)} />
      </PopoverContent>
    </Popover>
  );
}

Components API

TimePicker

Main component for time selection.

Prop	Type	Default	Description
value	TimeInput	required	Current time value (Date, string, or Time object)
onChange	(time: Time) => void	required	Callback when time changes
toggle	() => void	optional	Function to close picker
timepickerClassName	string	optional	Custom class for picker container
buttonClassName	string	optional	Custom class for increment/decrement buttons
sectionClassName	string	optional	Custom class for hour/minute sections
inputClassName	string	optional	Custom class for time input fields
periodToggleClassName	string	optional	Custom class for AM/PM toggle
closeButtonClassName	string	optional	Custom class for close button
incrementIcon	LucideIcon	ChevronUp	Custom icon for increment button
decrementIcon	LucideIcon	ChevronDown	Custom icon for decrement button
closeIcon	LucideIcon	X	Custom icon for close button

Popover Components

<Popover />

Container component that manages popover state.

Prop	Type	Default	Description
children	ReactNode	required	Popover content components
className	string	optional	Additional CSS classes

<PopoverTrigger />

Trigger element that toggles the popover.

Prop	Type	Default	Description
children	ReactNode	required	Element that triggers popover
className	string	optional	Additional CSS classes

<PopoverContent />

Content container for the popover.

Prop	Type	Default	Description
children	ReactNode	required	Content to display in popover
className	string	optional	Additional CSS classes
isAnimate	boolean	true	Enable/disable animations
variants	MotionProps	Default Animation	Framer Motion animation variants

Default Animation

{
  initial: { opacity: 0, y: "20%" },
  animate: { opacity: 1, y: "5%" },
  exit: { opacity: 0, y: "-20%" },
  transition: { duration: 0.2 }
}

Types

TimeInput

type TimeInput = Date | string | Time;

interface Time {
  hour: number; // 1-12
  minute: number; // 0-59
  period: "AM" | "PM";
}

Styling

The package uses Tailwind CSS for styling.
Import import "timepick-kit-react/index.css"; into your app component.

Utility Functions

formatTime

import { formatTime } from "timepick-kit-react";

const timeString = formatTime(new Date()); // Returns "hh:mm a" format

useTimePicker

import { useTimePicker } from "timepick-kit-react";

const { time, setHour, setMinute, setPeriod } = useTimePicker(initialValue);

useClickOutside

import { useClickOutside } from "timepick-kit-react";

useClickOutside(ref, handleClickOutside);

Features

Keyboard Navigation

• Up/Down arrows: Increment/decrement values
• Enter: Confirm selection
• Tab: Navigate between inputs
• Escape: Close picker

Customization

• Custom icons support
• Flexible styling with Tailwind CSS
• Animation customization via Framer Motion
• Light/Dark mode theming

Browser Support

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

License

MIT

Contributing

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

---

Created by David Jaja