Docs for the inbox Schedule page

content/docs/platform/inbox/configuration/meta.json

@@ -1,6 +1,6 @@
 {
   "title": "Customize and configure",
   "icon": "SlidersHorizontal",
-  "pages": ["styling", "icons", "tabs", "preferences", "snooze", "data-object"],
+  "pages": ["styling", "icons", "tabs", "preferences", "data-object"],
   "description": "Learn how to configure your inbox with styling, tabs, preferences, data objects, and snooze functionality"
 }

content/docs/platform/inbox/configuration/styling.mdx

@@ -160,6 +160,14 @@ Here's a list of some available elements that can be styled using the elements o
 | Snooze button                | `notificationSnooze__button`          |
 | Unread/read indicator button | `notificationUnread__button`          |
 | Notification list container  | `notificationList`                    |
+| Schedule container           | `scheduleContainer`                     |
+| Schedule header              | `scheduleHeader`                        |
+| Schedule body                | `scheduleBody`                          |
+| Schedule table               | `scheduleTable`                         |
+| Day schedule copy title      | `dayScheduleCopyTitle`                  |
+| Day schedule copy menu       | `dayScheduleCopy__dropdownContent`      |
+| Time select dropdown         | `timeSelect__dropdownTrigger`           |
+| Time select list             | `timeSelect__dropdownContent`           |
 
 <Callout type="info" title="How to find other elements?">
   Any selector that appears before the 🔔 emoji in the Devtools, can be targeted via the elements property in the appearance prop (stripping the `nv-` prefix). You can also use TS autocomplete to find the available elements.
@@ -352,6 +360,31 @@ You can customize specific parts of the Inbox UI by providing callback functions
 | `notificationDeliveredAt__icon`               | `(context: { notification: Notification }) => string`                                                             |
 | `notificationSnoozedUntil__icon`              | `(context: { notification: Notification }) => string`                                                             |
 | `notificationDot`                             | `(context: { notification: Notification }) => string`                                                             |
+| **Schedule**                              |                                                                 |
+| `scheduleContainer`                       | `(context: { schedule?: Schedule }) => string`                  |
+| `scheduleHeader`                          | `(context: { schedule?: Schedule }) => string`                  |
+| `scheduleLabelContainer`                  | `(context: { schedule?: Schedule }) => string`                  |
+| `scheduleLabelIcon`                       | `(context: { schedule?: Schedule }) => string`                  |
+| `scheduleLabel`                           | `(context: { schedule?: Schedule }) => string`                  |
+| `scheduleActionsContainer`                | `(context: { schedule?: Schedule }) => string`                  |
+| `scheduleActionsContainerRight`           | `(context: { schedule?: Schedule }) => string`                  |
+| `scheduleBody`                            | `(context: { schedule?: Schedule }) => string`                  |
+| `scheduleDescription`                     | `(context: { schedule?: Schedule }) => string`                  |
+| `scheduleTable`                           | `(context: { schedule?: Schedule }) => string`                  |
+| `scheduleTableHeader`                     | `(context: { schedule?: Schedule }) => string`                  |
+| `scheduleHeaderColumn`                    | `(context: { schedule?: Schedule }) => string`                  |
+| `scheduleTableBody`                       | `(context: { schedule?: Schedule }) => string`                  |
+| `scheduleBodyRow`                         | `(context: { schedule?: Schedule }) => string`                  |
+| `scheduleBodyColumn`                      | `(context: { schedule?: Schedule }) => string`                  |
+| `scheduleInfoContainer`                   | `(context: { schedule?: Schedule }) => string`                  |
+| `scheduleInfoIcon`                        | `(context: { schedule?: Schedule }) => string`                  |
+| `scheduleInfo`                            | `(context: { schedule?: Schedule }) => string`                  |
+| **Day Schedule Copy**                      |                                                                 |
+| `dayScheduleCopyTitle`                    | `(context: { schedule?: Schedule }) => string`                  |
+| `dayScheduleCopyIcon`                     | `(context: { schedule?: Schedule }) => string`                  |
+| `dayScheduleCopySelectAll`                | `(context: { schedule?: Schedule }) => string`                  |
+| `dayScheduleCopyDay`                      | `(context: { schedule?: Schedule }) => string`                  |
+| `dayScheduleCopyFooterContainer`          | `(context: { schedule?: Schedule }) => string`                  |
 
   </Accordion>
 </Accordions>

content/docs/platform/inbox/features/meta.json

@@ -0,0 +1,6 @@
+{
+  "title": "<Inbox /> Features",
+  "icon": "Blocks",
+  "pages": ["snooze", "schedule"],
+  "description": "Learn how to customize the appearance and behavior of the inbox component to match your application’s design system."
+}

content/docs/platform/inbox/features/schedule.mdx

@@ -0,0 +1,97 @@
+---
+title: 'Schedule'
+description: "Let subscribers choose when to receive in-app notifications with per-day availability windows and timezone-aware delivery."
+icon: 'CalendarCheck'
+---
+
+The **Schedule** feature in the <Method href="/platform/inbox/overview">{`<Inbox />`}</Method> lets subscribers control when they want to receive notifications. By defining availability hours, subscribers can pause in-app notifications outside their chosen time range.
+
+![](/images/inbox/schedule.png)
+
+<Callout>Notifications from critical workflows are never paused and will always be delivered, regardless of schedule settings.</Callout>
+
+## How Schedule works
+
+The schedule functionality is based on a clear set of rules controlled by the subscriber within the <Method href="/platform/inbox/overview">{`<Inbox />`}</Method>. When a subscriber enables their schedule, they can then manage their availability for each day of the week.
+
+### Daily availability
+For any day that the main schedule is active, there are two possible states:
+
+- **Day is enabled**: If a day is toggled on, the subscriber must set a time range. Notifications will only be delivered within these hours.
+
+- **Day is disabled**: If a day is toggled off, the subscriber will not receive any non-critical notifications for that entire day.
+
+### Automatic timezone handling
+
+The schedule operates in the subscriber's local timezone, detected automatically from their system settings. There is no need for manual configuration.
+
+For example, if a subscriber in Warsaw sets their schedule from 9:00 AM to 5:00 PM, they will receive notifications during those hours in Central European Time (CET).
+
+## Manage Schedule
+
+The schedule UI in the preferences section is designed to be intuitive, giving subscribers several tools to quickly configure their availability.
+
+You can access **Schedule** from the **Preferences** section of the <Method href="/platform/inbox/overview">{`<Inbox />`}</Method> UI. By default, scheduling is turned off, and all notifications are delivered normally.
+
+### Enable the main schedule
+
+The entire feature is controlled by a main schedule toggle. When a subscriber turns this on, they can begin configuring individual days. When it's off, all other settings are inactive, and notifications are delivered normally.
+
+### Setting daily availability
+
+For each day of the week, the subscriber can:
+
+- Use the toggle next to the day's name to activate or deactivate it.
+- If activated, use the time-selector dropdowns to set a "from" and "to" time. The time pickers are set to 30-minute increments for ease of use.
+
+### Edit or remove schedules
+
+Existing availability can be adjusted at any time. Subscribers can:
+- Change the start and end times for a day.
+- Re-enable a previously disabled day.
+- Clear a schedule entirely to return to unrestricted delivery.
+
+### Copying times to multiple days
+
+To make setup faster, subscribers can configure the time for one day and apply it to others in a few clicks:
+
+1. Set the desired time range for a single day (e.g., Wednesday from 9:00 AM to 5:00 PM).
+2. Click the "Copy times to..." button associated with that day.
+3. In the menu that appears, select the other days of the week to apply this schedule to.
+4. Click "Apply." The selected days will automatically be enabled and updated with the new time range.
+
+![Copying times to multiple days](/images/inbox/schedule.gif)
+
+### Automatic saving
+
+All changes made in the schedule interface are saved automatically in the background. The UI updates optimistically, providing a seamless experience without requiring the subscriber to click a "Save" button.
+
+## Set default schedule for Subscribers
+
+You can provide a default schedule for your subscribers by passing the `defaultSchedule` prop to the <Method href="/platform/inbox/overview">{`<Inbox />`}</Method>. This is useful for pre-configuring a recommended schedule that your subscribers can then customize.
+
+This default schedule will only be applied if a subscriber has not yet configured their own schedule. Once they make any changes, their custom schedule will take precedence.
+
+```tsx
+import { Inbox } from '@novu/react';
+
+function InboxWithDefaultSchedule() {
+  return (
+      <Inbox
+        applicationIdentifier="YOUR_APP_IDENTIFIER"
+        subscriberId="YOUR_SUBSCRIBER_ID"
+        defaultSchedule={{
+          isEnabled: true,
+          weeklySchedule: {
+            tuesday: {
+              isEnabled: true,
+              hours: [{start: '09:00 AM', end: '07:00 PM'}]
+            }
+          }
+        }}
+      />
+  );
+}
+
+export default InboxWithDefaultSchedule;
+```

content/docs/platform/inbox/meta.json

@@ -2,7 +2,7 @@
   "pages": [
     "overview",
     "setup-inbox",
-    "navigation-and-events",
+    "features",
     "configuration",
     "advanced-customization",
     "advanced-concepts",

content/docs/platform/sdks/react/hooks/use-schedule.mdx

@@ -0,0 +1,181 @@
+---
+title: "useSchedule"
+description: "Learn how to use the useSchedule hook to manage subscriber notification schedules in your React application"
+---
+
+import { TypeTable } from 'fumadocs-ui/components/type-table';
+import { Tab, Tabs } from "fumadocs-ui/components/tabs";
+
+Schedules define when notifications should be delivered by setting availability hours across days of the week. The `useSchedule` hook provides a way to fetch, display, and update the notification schedule for the current subscriber.
+
+## Hook parameters
+
+<TypeTable
+  type={{
+    onSuccess: {
+      type: "(data: Schedule) => void",
+      description:
+        "Callback function called when the schedule is successfully fetched",
+    },
+    onError: {
+      type: "(error: NovuError) => void",
+      description: "Callback function called when an error occurs",
+    },
+  }}
+/>
+
+## Return value
+
+<TypeTable
+  type={{
+    schedule: {
+      type: "Schedule | undefined",
+      description: "The subscriber's current schedule object",
+      typeDescription: "undefined if data is not yet loaded",
+    },
+    error: {
+      type: "NovuError | undefined",
+      description: "Error object if the request failed",
+    },
+    isLoading: {
+      type: "boolean",
+      description: "True during the initial load, false otherwise",
+      default: "true",
+    },
+    isFetching: {
+      type: "boolean",
+      description:
+        "True while any request is in flight (initial load or refetch), false otherwise",
+      default: "true",
+    },
+    refetch: {
+      type: "() => Promise<void>",
+      description: "Function to manually trigger a refetch of the schedule",
+    },
+  }}
+/>
+
+## Schedule type
+
+The `Schedule` type from `@novu/react` includes these properties:
+
+<TypeTable
+  type={{
+    isEnabled: {
+      type: "boolean",
+      description: "Global flag to enable or disable the entire schedule.",
+    },
+    weeklySchedule: {
+      type: "object",
+      description: "An object containing the schedule for each day of the week (for example, monday, tuesday). Each key holds a DaySchedule object.",
+    },
+  }}
+/>
+
+Each `DaySchedule` object within `weeklySchedule` has the following structure:
+
+<TypeTable
+  type={{
+    isEnabled: {
+      type: "boolean",
+      description: "Flag to enable or disable the schedule for this specific day.",
+    },
+    hours: {
+      type: "Array<{ start: string; end: string; }>",
+      description: "An array of time ranges for when notifications are allowed. Multiple ranges per day are supported (for example, 9-12 AM and 2-5 PM).",
+    },
+  }}
+/>
+
+## Updating the schedule
+
+The hook also allows updating the subscriber’s schedule via `schedule.update`:
+
+```tsx
+const handleClick = async () => {
+  await schedule?.update({
+    isEnabled: true,
+    weeklySchedule: {
+      monday: {
+        isEnabled: true,
+        hours: [{ start: '08:00 AM', end: '18:00 PM' }],
+      },
+    }
+  })
+};
+```
+
+## Example usage
+
+Here's how to use the `useSchedule` hook to display and update a subscriber's notification schedule. The `schedule.update()` method will create a schedule if one doesn't exist or update the existing one.
+
+```tsx
+import { useSchedule } from "@novu/react";
+
+function ScheduleManager() {
+  const { schedule, isLoading, error, refetch } = useSchedule();
+
+  if (isLoading) return <div>Loading schedule...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  const handleUpdateSchedule = async () => {
+    try {
+      await schedule?.update({
+        isEnabled: true,
+        weeklySchedule: {
+          monday: {
+            isEnabled: true,
+            hours: [
+              { start: '09:00 AM', end: '12:00 PM' },
+              { start: '02:00 PM', end: '05:00 PM' },
+            ],
+          },
+          tuesday: {
+            isEnabled: true,
+            hours: [{ start: '09:00 AM', end: '05:00 PM' }],
+          },
+          // Other days can be left undefined or explicitly disabled
+          wednesday: {
+            isEnabled: false,
+            hours: [],
+          },
+        },
+      });
+
+      // Refresh the schedule data after updating
+      refetch();
+    } catch (e) {
+      console.error("Failed to update schedule:", e);
+    }
+  };
+
+  return (
+    <div className="p-4 border rounded-lg">
+      <h3 className="font-medium">My Notification Schedule</h3>
+      <p>
+        Schedule Enabled: <strong>{schedule?.isEnabled ? 'Yes' : 'No'}</strong>
+      </p>
+
+      <div className="mt-2">
+        <h4 className="font-medium">Monday Hours:</h4>
+        {schedule?.weeklySchedule?.monday?.isEnabled ? (
+          <ul className="list-disc pl-5">
+            {schedule.weeklySchedule.monday.hours.map((range, index) => (
+              <li key={index}>{`${range.start} - ${range.end}`}</li>
+            ))}
+          </ul>
+        ) : (
+          <p>Not scheduled</p>
+        )}
+      </div>
+
+      <button
+        onClick={handleUpdateSchedule}
+        className="mt-4 px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700"
+      >
+        Set Default Work Hours
+      </button>
+    </div>
+  );
+}
+```