Skip to main content
Version: 1.5.x

Props

Props

EngagespotProps are configuration options for customizing and integrating the Engagespot notification panel in your application. These options include visual styling, notification behavior, and event handling.

Visual and Theming Options​

  • theme (ThemeOverrides)
    Customize the theme to align with your app's branding by overriding default styles, including colors, fonts, and layout.

  • feedItemPlaceholderImage (string)
    Placeholder image displayed when a notification lacks a specific image.

  • headerText (string)
    Text displayed at the top of the notification panel, typically a title or heading.

  • hideNotificationAvatar (boolean)
    Hides the avatar image shown alongside each notification item in the feed.

  • hideJumpToTop (boolean)
    Toggles visibility of the button that scrolls to the top of the feed.

  • disableNotificationChime (boolean)
    Disables the chime sound when a new notification is received. Defaults to true.

  • notificationChimeSrc (string)
    Path or URL for the audio file used for the notification chime.

  • hideCategoryTabs (boolean)
    When true, hides category tabs, showing all notifications in a single feed.

Custom Rendering Options​

  • renderFooterContent (customRenderFn)
    Custom function to render footer content in the panel, allowing for links or other specific content.

  • renderNotificationIcon (customRenderFn)
    Custom icon renderer for the main notification icon.

  • renderEmptyPlaceholderImage (customRenderFn)
    Renders a custom image when no notifications are available.

  • renderNotificationContent (customRenderFn<customNotificationContentType>)
    Customize the content display for each notification item.

  • renderNotificationBody (customRenderFn<customNotificationContentType>)
    Provides granular control over the text or components within the notification body.

Behavior and Functionality​

  • panelOpenByDefault (boolean)
    Automatically opens the notification panel when the component is loaded for the first time.

  • panelOnly (boolean)
    Enables panel-only mode, hiding other UI elements and displaying only the notification panel.

  • onFeedItemClick (onFeedItemClickType)
    Callback function triggered when a notification item is clicked, useful for navigation or custom actions.

  • formatDate ((dateString: string, dateFns: typeof dateFunctions) => string)
    Function to format dates within notifications, useful for custom date formats.

  • textOverrides (TextOverridesPartial)
    Allows overriding default text in the notification panel for custom wording or localization.

Event and Interaction Settings​

  • eventListenersToRun (EventListenersToRun[])
    List of event listeners for the panel, defining specific actions triggered by events.

  • headerDropdownItems (DropdownMenuProps['items'])
    Custom dropdown items displayed in the panel header, useful for quick settings or filters.

  • profile ({ [attribute: string]: any })
    Object to dynamically edit user profile attributes.

  • events (Partial<EventCallbackMap>)
    Register callbacks for notification events from the store instance.

Advanced Options​

  • panel (PanelProps)
    Additional configurations for the floating panel.

  • disableTextTranslation (boolean)
    Disables automatic text translation, useful for non-translatable content.

  • toast (Partial<ToastProps>)
    Toast notification settings, allowing overrides for properties like position and duration.

  • enableErrorBoundary (boolean)
    Enables error boundaries around the notification panel, capturing unexpected errors.

  • actionableElements (Partial<ActionableElements>)
    Customize behavior and properties for specific template block types within the notification panel. This allows for tailored configurations for interactive elements like text areas or rating stars.

Supported Template Block Types:​

  1. textarea
    Customize properties such as auto-growth and change handlers for text area inputs.

    • autoGrow (boolean): Enables auto-expansion of the text area as the user types.
    • onChange ((e: React.ChangeEvent<HTMLTextAreaElement>) => void): Callback triggered on text input change.

  2. rating-star
    Configure options for rating star components.

    • icon (React.ReactNode): Custom icon for the stars.
    • activeIcon (React.ReactNode): Icon used for active (selected) stars.
    • onChange ((value: number) => void): Callback triggered when a rating is selected.

Store Options​

  • disableRealTimeStoreUpdates (boolean)
    If true, real-time store updates are disabled, and notifications won't automatically update with real-time events.

  • disableFetchOnStart (boolean)
    Disables initial fetch of notifications when the store is created.

  • itemsPerPage (number)
    Limits the number of notifications fetched per page.

  • relativeTimeUpdateInterval (number)
    Interval (in milliseconds) to update relative time displays (e.g., "5 minutes ago").

Instance Options​

  • userId (string)
    Unique identifier for the user.

  • tenantIdentifier (string)
    Unique identifier for the tenant (optional).

  • apiKey (string)
    API key for accessing Engagespot services.

  • userSignature (string)
    Deprecated. User-specific signature (use userToken for secure mode).

  • userToken (string)
    Token for secure mode, enforcing token-based authentication.

  • disableWebPush (boolean)
    Disables web push notifications (defaults to false).

  • allowNonHttpsWebPush (boolean)
    Allows web push on non-HTTPS domains, useful for development (defaults to false).

  • serviceWorkerRegistration (ServiceWorkerRegistration)
    Service worker registration object for push notifications.

  • disableRtm (boolean)
    Disables real-time messages (defaults to false).

  • baseUrl (string)
    Custom base URL for Engagespot server, necessary if hosted on a different domain.

  • debug (boolean)
    Enables debug mode for additional logging (defaults to false).

  • disableAutoStart (boolean)
    Prevents Engagespot from automatically calling connect() and realTime() on startup.

Type Definitions​

type EngagespotProps = {
  userId: string;
  tenantIdentifier?: string;
  apiKey: string;
  userSignature?: string;
  userToken?: string;
  disableWebPush?: boolean;
  allowNonHttpsWebPush?: boolean;
  serviceWorkerRegistration?: ServiceWorkerRegistration;
  disableRtm?: boolean;
  baseUrl?: string;
  debug?: boolean;
  disableAutoStart?: boolean;
  disableRealTimeStoreUpdates?: boolean;
  disableFetchOnStart?: boolean;
  itemsPerPage?: number;
  relativeTimeUpdateInterval?: number;
  theme: ThemeOverrides;
  panelOpenByDefault: boolean;
  panelOnly: boolean;
  feedItemPlaceholderImage: string;
  hideNotificationAvatar: boolean;
  hideJumpToTop: boolean;
  headerText: string;
  renderFooterContent: customRenderFn;
  renderNotificationIcon: customRenderFn;
  renderEmptyPlaceholderImage: customRenderFn;
  onFeedItemClick: onFeedItemClickType;
  textOverrides: TextOverridesPartial;
  renderNotificationContent: customRenderFn<customNotificationContentType>;
  renderNotificationBody: customRenderFn<customNotificationContentType>;
  eventListenersToRun: EventListenersToRun[];
  headerDropdownItems: DropdownMenuProps['items'];
  formatDate: (dateString: string, dateFns: typeof dateFunctions) => string;
  disableNotificationChime: boolean;
  notificationChimeSrc: string;
  panel: PanelProps;
  disableTextTranslation: boolean;
  toast: Partial<ToastProps>;
  hideCategoryTabs: boolean;
  enableErrorBoundary: boolean;
  profile?: {
    [attribute: string]: any;
  };
  events?: Partial<EventCallbackMap>;
  actionableElements?: Partial<ActionableElements>;
};

type defaultRenderFn = (...args: unknown[]) => ReactNode | string;

type customRenderFn<T = defaultRenderFn> = T | undefined;

type NotificationReceiveEvent = { notification: EngagespotNotification };

type ClickableNotificationPayload = {
  url?: string | null;
  id: number;
  markAsClicked: () => void;
};

type onFeedItemClickType = (
  evt: ReactMouseEvent<HTMLDivElement, MouseEvent>,
  payload: ClickableNotificationPayload,
) => void;

type PanelProps = {
  isOpen: boolean;
  setIsOpen: (isOpen: boolean) => void;
  disableDismiss?: boolean;
};

type ToastProps = {
  enableToast: boolean;
  toasterProps: Partial<ToasterProps>;
  toastProps: {
    renderToast?: (prop: {
      notificationReceiveEvent: NotificationReceiveEvent;
      toast: typeof sonnerToast;
    }) => void;
    message?: (notificationReceiveEvent: NotificationReceiveEvent) => string;
    description?: (
      notificationReceiveEvent: NotificationReceiveEvent,
    ) => string;
    options?: (
      notificationReceiveEvent: NotificationReceiveEvent,
    ) => Omit<ExternalToast, 'description'>;
  };
};

type EventListenersToRun = {
    blockId: string;
    event: ReactEvent;
    onEvent: ({ event, notification, changeNotificationState, getValue, }: {
        event: ReactEventHandler;
        notification: EngagespotNotification;
        changeNotificationState: changeNotificationStateFnType;
        getValue: (id: string) => string;
    }) => void;
};

type EventCallback<T> = (params: T) => void;
type Events = ReturnType<typeof initializeEvents>;

type EventCallbackMap = {
  notificationReceive: EventCallback<NotificationReceiveEvent>;
  notificationDelete: EventCallback<NotificationDeleteEvent>;
  notificationRead: EventCallback<NotificationClickEvent>;
  notificationSeen: EventCallback<NotificationSeenEvent>;
  notificationReadAll: EventCallback<NotificationReadAll>;
  notificationDeleteAll: EventCallback<NotificationDeleteAll>;
  notificationStateChange: EventCallback<NotificationStateChange>;
};

type RatingStarStyledProps = {
    icon?: React.ReactNode;
    activeIcon?: React.ReactNode;
    onChange?: (value: number) => void;
};

type TextAreaStyledProps = {
    autoGrow?: boolean;
    onChange?: (e: React.ChangeEvent<HTMLTextAreaElement>) => void;
    ref?: React.RefObject<HTMLTextAreaElement>;
};

type TemplateBlockBase = {
    id: string;
    text?: string;
    variant?: 'default' | 'primary' | 'secondary';
};
type BlockTypes = {
    type: 'button';
    link?: string;
    externalLink?: boolean;
} | {
    type: 'rating-star';
} | {
    type: 'image';
    src?: string | Blob[];
} | {
    type: 'textarea';
};
type TemplateBlock = TemplateBlockBase & BlockTypes;
type TemplateBlockTypes = Exclude<TemplateBlock['type'], 'button' | 'image'>;

type ActionableElements = {
    [Key in TemplateBlockTypes]?: Key extends 'textarea' ? Exclude<TextAreaStyledProps, 'ref'> : Key extends 'rating-star' ? RatingStarStyledProps : never;
};