react-native-scheduled-view

v0.2.0

Published

6 months ago

Show and hide React Native components based on time schedules

🕒 React Native Scheduled View

Show and hide React Native components based on time schedules using the device's local clock

Installation • Quick Start • Examples • API Reference

✨ Features

🕒 Smart Scheduling
Schedule components for specific times and days with precision

⚡ Lightweight
Minimal overhead with optimized performance

🌍 Local Time Based
Uses device's local clock for accurate timing

📱 Cross Platform
Works seamlessly on iOS and Android

🔄 Flexible Scheduling
Daily and span-based scheduling options

🎯 Priority System
Handle overlapping time ranges with priorities

📦 Installation

# Using npm
npm install react-native-scheduled-view

# Using yarn
yarn add react-native-scheduled-view

# Using pnpm
pnpm add react-native-scheduled-view

Note: No additional configuration required! Works out of the box with Expo and bare React Native projects.

🚀 Quick Start

import React from 'react';
import { Text, View, StyleSheet } from 'react-native';
import ScheduledView from 'react-native-scheduled-view';

export default function App() {
  return (
    <View style={styles.container}>
      <ScheduledView
        ranges={[
          {
            type: 'daily',
            start: '09:00',
            end: '17:00',
            days: [1, 2, 3, 4, 5], // Monday to Friday
          },
        ]}
      >
        <Text style={styles.text}>💼 Only visible during business hours!</Text>
      </ScheduledView>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
  text: {
    fontSize: 18,
    textAlign: 'center',
  },
});

📚 Examples

Advanced Scheduling with Priority

import React from 'react';
import ScheduledView, {
  FULL_WEEK,
  WEEKENDS,
} from 'react-native-scheduled-view';

const ranges = [
  // Default: 10 AM - 10 PM all week (lower priority)
  {
    type: 'daily',
    start: '10:00',
    end: '22:00',
    priority: 10,
    days: FULL_WEEK,
  },
  // Override: Earlier close on weekends (higher priority)
  {
    type: 'daily',
    start: '10:00',
    end: '18:00',
    priority: 1, // Higher priority (lower number)
    days: WEEKENDS,
  },
];

export default function StoreHours() {
  return (
    <ScheduledView ranges={ranges}>
      <StoreOpenBanner />
    </ScheduledView>
  );
}

Weekend Special Promotions

<ScheduledView
  ranges={[
    {
      type: 'daily',
      start: '12:00',
      end: '20:00',
      days: WEEKENDS,
    },
  ]}
>
  <WeekendPromotionBanner />
</ScheduledView>

Cross-Day Events (Friday Night to Monday Morning)

<ScheduledView
  ranges={[
    {
      type: 'span',
      startTime: '20:00', // Friday 8 PM
      endTime: '08:00', // Monday 8 AM
      startDay: 5, // Friday
      endDay: 1, // Monday
    },
  ]}
>
  <WeekendModeInterface />
</ScheduledView>

📖 API Reference

`<ScheduledView>` Props

| Prop | Type | Required | Description | | ---------- | -------------------- | -------- | -------------------------------------------------------------------- | | ranges | TimeConfig[] | ✅ | Array of time configurations defining when content should be visible | | children | React.ReactElement | ❌ | Component to conditionally render based on schedule |

Time Configuration Types

📅 Daily Schedule

Perfect for recurring daily schedules like business hours or daily events.

interface DailyTimeConfig {
  type: 'daily';
  start: string; // Time in HH:MM format (24-hour)
  end: string; // Time in HH:MM format (24-hour)
  days: number[]; // Day numbers (0=Sunday, 1=Monday, ..., 6=Saturday)
  priority?: number; // Lower numbers = higher priority (default: 10)
}

🔄 Span Schedule

For events that cross multiple days, like weekend events or maintenance windows.

interface SpanTimeConfig {
  type: 'span';
  startTime: string; // Start time in HH:MM format
  endTime: string; // End time in HH:MM format
  startDay: number; // Starting day of the week
  endDay: number; // Ending day of the week
  priority?: number; // Lower numbers = higher priority (default: 10)
}

📅 Day Constants

Pre-defined day arrays for common scheduling patterns:

import { FULL_WEEK, WEEK_DAYS, WEEKENDS } from 'react-native-scheduled-view';

// Available constants:
FULL_WEEK = [0, 1, 2, 3, 4, 5, 6]; // All days
WEEK_DAYS = [1, 2, 3, 4, 5]; // Monday to Friday
WEEKENDS = [0, 6]; // Sunday and Saturday

Priority System

When multiple time ranges overlap, the range with the lower priority number takes precedence:

Priority 1 beats Priority 10
Default priority is 10
Use priorities to create exceptions to general rules

Using TimeRangeManager Directly

If you prefer to handle time tracking logic yourself instead of using the ScheduledView component, you can use the TimeRangeManager class directly. This gives you more control over when and how to respond to time-based events.

Basic Usage

import React, { useState, useEffect } from 'react';
import { View, Text } from 'react-native';
import { TimeRangeManager } from 'react-native-scheduled-view';

export default function CustomScheduledComponent() {
  const [isVisible, setIsVisible] = useState(false);

  useEffect(() => {
    const subscription = TimeRangeManager.registerTime(
      [
        {
          type: 'daily',
          start: '09:00',
          end: '17:00',
          days: [1, 2, 3, 4, 5], // Monday to Friday
        },
      ],
      () => setIsVisible(true), // onShow callback
      () => setIsVisible(false) // onHide callback
    );

    // Cleanup subscription on unmount
    return () => subscription.remove();
  }, []);

  return (
    <View>
      {isVisible && <Text>Content visible during business hours!</Text>}
      {!isVisible && <Text>Currently outside business hours</Text>}
    </View>
  );
}

Advanced Usage with Multiple Handlers

import React, { useState, useEffect } from 'react';
import { TimeRangeManager, WEEKENDS } from 'react-native-scheduled-view';

export default function AdvancedScheduledComponent() {
  const [businessHours, setBusinessHours] = useState(false);
  const [weekendMode, setWeekendMode] = useState(false);

  useEffect(() => {
    // Track business hours
    const businessSubscription = TimeRangeManager.registerTime(
      [{ type: 'daily', start: '09:00', end: '17:00', days: [1, 2, 3, 4, 5] }],
      () => setBusinessHours(true),
      () => setBusinessHours(false)
    );

    // Track weekend periods
    const weekendSubscription = TimeRangeManager.registerTime(
      [{ type: 'daily', start: '10:00', end: '20:00', days: WEEKENDS }],
      () => setWeekendMode(true),
      () => setWeekendMode(false)
    );

    return () => {
      businessSubscription.remove();
      weekendSubscription.remove();
    };
  }, []);

  return (
    <View>
      <Text>Business Hours: {businessHours ? 'Open' : 'Closed'}</Text>
      <Text>Weekend Mode: {weekendMode ? 'Active' : 'Inactive'}</Text>
    </View>
  );
}

TimeRangeManager API

`registerTime(ranges, onShow, onHide)`

ranges: Array of TimeConfig objects (same as ScheduledView)
onShow: Callback function called when any range becomes active
onHide: Callback function called when no ranges are active
Returns: Object with remove() method to unsubscribe

Important: Always call remove() in cleanup to prevent memory leaks and ensure proper resource management.

💡 Common Use Cases

<ScheduledView
  ranges={[
    {
      type: 'daily',
      start: '09:00',
      end: '17:00',
      days: WEEK_DAYS,
    },
  ]}
>
  <ContactForm />
</ScheduledView>

<ScheduledView
  ranges={[
    {
      type: 'daily',
      start: '12:00',
      end: '20:00',
      days: WEEKENDS,
    },
  ]}
>
  <WeekendPromotion />
</ScheduledView>

<ScheduledView
  ranges={[
    {
      type: 'span',
      startTime: '20:00', // Friday evening
      endTime: '08:00', // Monday morning
      startDay: 5, // Friday
      endDay: 1, // Monday
    },
  ]}
>
  <WeekendModeInterface />
</ScheduledView>

const holidaySchedule = [
  // Regular hours (lower priority)
  {
    type: 'daily',
    start: '09:00',
    end: '17:00',
    days: WEEK_DAYS,
    priority: 10,
  },
  // Holiday exception (higher priority)
  {
    type: 'daily',
    start: '12:00',
    end: '15:00',
    days: [1], // Monday only
    priority: 1,
  },
];

<ScheduledView ranges={holidaySchedule}>
  <StoreHours />
</ScheduledView>;

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⬆ Back to top