@symbiot.dev/react-native-timegrid v0.2.4

A powerful and flexible time grid and calendar component for React Native, designed to work seamlessly across iOS, Android, Web, Expo, and Expo Go. Built for performance and customization, react-native-timegrid enables developers to implement rich, interactive calendar views for a wide range of scheduling and planning needs.

📱 Demo

✨ Key Features

📆 Time-Based Grid Layout – Intuitive hourly/daily layout ideal for agenda, schedule, or shift views.

🎨 Fully Customizable – Modify headers, time slots, event appearance, and grid styling to fit any design system.

🧠 Lightweight – Minimal dependencies and optimized bundle size for faster load times and efficient performance.

🚀 Cross-Platform Compatibility – Works out of the box with:

• React Native CLI
• Expo
• Expo Go
• React Native Web for browser support

⚙️ Optimized Performance – Supports virtual scrolling and large datasets with smooth interactions.

✋ Interactive Features – Tap, drag, and dynamic updates for real-time scheduling apps.

📱 Responsive Design – Adapts to various screen sizes and device orientations.

🧩 Modular Integration – Use as a standalone calendar or integrate into more complex scheduling systems.

🛠 Ideal For

• 📅 Personal or team calendars
• 🛎️ Booking and reservation systems (salons, gyms, clinics)
• 👥 Employee shift and availability planners
• 📆 Event timeline visualizations
• 🧑‍🏫 Class schedules and academic timetables
• 🧠 Task and time management tools
• 🏥 Appointment scheduling for healthcare or therapy
• 📦 Delivery or logistics scheduling
• 💼 Project planning dashboards with time allocation
• 🛠 Maintenance or service job assignment trackers
• 🎓 Student agendas or learning planners
• 🎤 Conference session planners and expo booth schedules
• 🔥 and more ...

Whether you're building a cross-platform scheduling app or integrating a responsive calendar view into an existing project, react-native-timegrid provides a modern, customizable, and performant solution for all major platforms.

👩🏿‍💻 Installation

npm install @symbiot.dev/react-native-timegrid react-native-reanimated react-native-gesture-handler date-fns
# or
yarn add @symbiot.dev/react-native-timegrid react-native-reanimated react-native-gesture-handler date-fns

# for web support
npm i react-native-web
# or
yarn add react-native-web

# to support recurring events
npm i rrule
# or
yarn add rrule

import { TimeGrid } from '@symbiot.dev/react-native-timegrid';

// ... and voilà 💫
<TimeGrid />

Just import it and boom — you’ve got a slick, cross-platform calendar view. Fast setup, full control, and zero headaches. 💪🏻💥

🎨 TimeGridThemeProps – Theming & Appearance

Customize the look and feel of the TimeGrid with flexible styling options. You can define global styles, override them based on theme (light or dark), or combine both approaches.

🧩 Structure

The TimeGridThemeProps type supports three layers:

1. Global Styling (applies to all schemes unless overridden)
2. Per-scheme Overrides – Use light and dark keys to define specific values
3. Theme Scheme Selector – Control active theme using scheme

type TimeGridThemeProps = TimeGridStyling & {
  scheme?: 'light' | 'dark'; // system default
  light?: TimeGridStyling;
  dark?: TimeGridStyling;
};

🧱 Available Styling Props

<TimeGrid
  //...
  theme={{
    backgroundColor: '#f0f0f0', // for light and dark mode
  }}
/>

// ----

<TimeGrid
  //...
  theme={{
    backgroundColor: '#f0f0f0', // only applies to light mode
    eventTextColor: '#323232', // only applies to dark mode
    dark: {
      backgroundColor: '#020202',
    },
    light: {
      eventTextColor: '#505050',
    }
  }}
/>

📐 TimeGridDimensionsProps – Layout & Dimensions

Control the physical dimensions of key areas inside the TimeGrid. All values are in pixels and optional — sensible defaults are provided.

🧱 Available Dimension Props

<TimeGrid
  //...
  timelineWidth={60}
/>

📅 TimeGridDatetimeProps – Date & Time Configuration

Set the visible time range, number of days, start date, timezone, and other calendar-related behaviors.
These props give you precise control over how the TimeGrid renders days and time slots.

🧱 Available Datetime Props

<TimeGrid
  //...
  weekStartsOn={1} // starts on Monday
  numberOfDays={3}
  hiddenDays={[0, 6]} // exclude weekends (Sun,Sut)
/>

🗓️ TimeGridEventsProps – Events, Rendering & Recurrence

Configure how events appear and behave inside the calendar. Supports custom colors, recurring events, readonly mode, and timezone-specific scheduling.

🟦🟨 Overlapping Events
Events that share time ranges are fully supported out-of-the-box.
The grid will automatically stack or split them side-by-side depending on layout space.

🧱 Available Event Props

TimeGridEvent

ℹ️ Need help creating a recurrence rule?
Use the visual generator at rrule.js playground to quickly create and test valid RRULE strings.

<TimeGrid
  //...
  createEventDuration={30} // new created events equals 30 mins
  events={[
    //...
    {
      id: 'timestamp',
      start: '2025-04-25T18:00:00.500Z',
      end: '2025-04-25T19:00:00.800Z',
      backgroundColor: '#DDDDDD',
      textColor: '#000000',
      readonly: true // prevent from being dragged
    }
  ]}
/>

🚫 TimeGridUnavailableTimeProps – Blocking Unavailable Times

Mark specific time ranges as unavailable — either for a specific date or recurring on weekdays.
These periods can block event creation, display with a distinct background and could be used with a different combinations.

export type TimeGridUnavailableTime = {
  from: number; // in minutes (e.g. 480 = 8:00 AM)
  to: number;   // in minutes (e.g. 1020 = 5:00 PM)
  start?: Date | string;
  end?: Date | string;
} & (
  | {
  weekday?: Day;   // 0 (Sunday) to 6 (Saturday)
  date?: never;
}
  | {
  date?: Date | string;
  weekday?: never;
}
  );

export type TimeGridUnavailableTimeProps = {
  unavailableTime?: TimeGridUnavailableTime[];
};

🧱 Available Unavailable Time Props

<TimeGrid
  //...
  unavailableTime={[
    { from: 0, to: 480 } // everyday 00:00 (12:00 AM) -> 08:00 AM
  ]}
/>

// ----

<TimeGrid
  //...
  unavailableTime={[
    { from: 0, to: 480, start: '2025-04-25T18:00:00.500Z' } // daily, starting April 25
  ]}
/>

// ----

<TimeGrid
  //...
  unavailableTime={[
    { from: 0, to: 480, start: '2025-04-25T00:00:00.500Z', end: '2025-04-26T00:00:00.500Z' } // only 2 days - April 25 and 26
  ]}
/>

// ----
// Priority behaviour

<TimeGrid
  //...
  unavailableTime={[
    { from: 0, to: 480 }, // daily
    { from: 1020, to: 1440, weekday: 1 }, // ignore the first element of the array and apply every Monday
    { from: 480, to: 900, date: '2025-04-28T18:00:00.500Z' } // ignore the first and second rules for Monday, April 28th
  ]}
/>

// ----
// Save behaviour

<TimeGrid
  //...
  unavailableTime={[
    { from: 0, to: 480 }, // daily
    { from: 0, to: 480, date: '2025-04-28T18:00:00.500Z' }, // save the daily rule for April 28
    { from: 480, to: 900, date: '2025-04-28T18:00:00.500Z' } // ignore the first and second rules for Monday, April 28th
  ]}
/>

🎮 TimeGridControllerProps – Interaction & Display Toggles

Control user interaction features like swiping, dragging, snapping, and visibility of UI components like the timeline, all-day events etc.

🧱 Available Controller Props

<TimeGrid
  //...
  swipeable // swipe actions turned on
  draggable // user can drag events
  snappable // date snapping enabled
/>

⏱ TimeGridFormatterProps – Text Formatting

Customize how dates and times appear within the TimeGrid component using format strings (e.g., dd, HH:mm, EEE).
These follow date-fns formatting syntax.

🧱 Available Formatter Props

import { zhCN } from 'date-fns/locale/zh-CN';

<TimeGrid
  //...
  locale={zhCN} // Chinese localization
/>

🎯 TimeGridActionsProps – User Interaction Callbacks

Listen and respond to interactions like taps, long presses, event edits, and grid context menus.

🧱 Available Action Callbacks

import { useState } from 'react';

const [selectedDate, setSelectedDate] = useState(new Date());

<TimeGrid
  //...
  onChangeDate={setSelectedDate} // selectedDate updated
/>

🔧 TimeGridRef – Imperative Control API

Control and interact with the TimeGrid instance programmatically using a React ref.
Great for custom toolbars, buttons, or dynamic navigation.

🧱 Available Ref Methods

import { useRef } from 'react';
import { TimeGrid, TimeGridRef } from '@symbiot.dev/react-native-timegrid';

const timeGridRef = useRef<TimeGridRef>(null);

<TimeGrid
  //...
  ref={timeGridRef}
  onDatetimeLongPress={(params) => timeGridRef.current?.createEvent(params)}
/>

🌐 Platform Support

• ✅ iOS
• ✅ Android
• ✅ Web
• ✅ Expo & Expo Go

📦 Bundle Size

Lightweight and fast — see actual size on Bundlephobia.

💬 Contributing

Contributions welcome! Feel free to open issues, discussions, or suggestions.

🌟 Who's Using This?

Using react-native-timegrid in your app or product?
Feel free to share your project — it might be featured in this section!

✉️ Open pull request, or reach out directly to get included.

🚀 Got Ideas or Gaps to Fill?

Know of existing libraries or functionality that could be improved?
Have an idea for something completely new?

Symbiot is ready to take on the challenge — feedback, feature requests, or collaboration ideas are always welcome!

🧠 Let’s build better tools together. Start the conversation or contact via email.

🧾 License

MIT — Made with ❤️ by Symbiot