​
Overview

The @sirenapp/vue-inbox SDK is a comprehensive and customizable Vue 3 UI kit for displaying and managing notifications. This documentation provides comprehensive information on how to install, configure, and use the SDK effectively.

​
Installation

You can install the Vue SDK from npm or yarn 
npm install @sirenapp/vue-inbox

​
Prerequisites

  • Vue 3 (v3.0.0+)

​
Configuration

​
Initialization

Initialize the SDK with user token and recipient ID. Wrap the provider around your app’s root component: 
<template>
  <SirenProvider :config="config">
    <-- Your app components -->
  </SirenProvider>
</template>
<script setup lang="ts">
import { SirenProvider } from "@sirenapp/vue-inbox";
const config = {
  userToken: "your_user_token",
  recipientId: "your_recipient_id",
};
</script>

​
Configure Notification Inbox

Once the provider is configured, add the notification inbox component: 
<template>
  <SirenInbox />
</template>
<script setup lang="ts">
import { SirenInbox } from "@sirenapp/vue-inbox";
</script>

​
Inbox Props

PropDescriptionTypeDefault
themeObject for custom themesTheme{}
customStylesObject for custom stylingCustomStyle{}
loadMoreLabelText shown on the load more componentstring”Load More”
hideBadgeToggle to hide or show the badgebooleanfalse
darkModeToggle to enable dark modebooleanfalse
itemsPerFetchNumber of notifications per API request (max 50)number20
windowViewOnlyToggle for fit-to-screen window or modal viewbooleanfalse
headerPropsProps for customizing the headerHeaderProps{ title: 'Notifications', hideHeader: false, hideClearAll: false }
cardPropsProps for customizing notification cardsCardProps{ hideDelete: false, hideAvatar: false, disableAutoMarkAsRead: false, onAvatarClick: ()=>null }
onCardClickClick handler for notification cards(notification) => void() => null
onErrorError handler(error: SirenErrorType) => void() => null

​
CardProps

type CardProps = {
  hideDelete?: boolean;
  hideAvatar?: boolean;
  onAvatarClick?: (notification: NotificationDataType) => void;
  disableAutoMarkAsRead?: boolean;
};

​
HeaderProps

type HeaderProps = {
  title?: string;
  hideHeader?: boolean;
  hideClearAll?: boolean;
};

​
Inbox Slots

Customize components using these slots:
SlotDescription
loadMoreComponentCustom load more button component
customHeaderCustom header component
customLoaderCustom loader component
customErrorWindowCustom error window
listEmptyComponentCustom empty list component
customCardCustom notification card component
customFooterCustom footer component
notificationIconCustom notification icon component

​
Customization

Theme Customization
type Theme = {
  dark: ThemeProps,
  light: ThemeProps,
};
type ThemeProps = {
  colors?: {
    primaryColor?: string,
    textColor?: string,
    neutralColor?: string,
    borderColor?: string,
    highlightedCardColor?: string,
    dateColor?: string,
    deleteIcon?: string,
    timerIcon?: string,
    clearAllIcon?: string,
    infiniteLoader?: string,
    windowShadowColor?: string,
  },
  badgeStyle?: {
    color?: string,
    textColor?: string,
  },
  windowHeader?: {
    background?: string,
    titleColor?: string,
    headerActionColor?: string,
  },
  windowContainer?: {
    background?: string,
  },
  customCard?: {
    borderColor?: string,
    background?: string,
    titleColor?: string,
    subtitleColor?: string,
    descriptionColor?: string,
  },
  loadMoreButton?: {
    color?: string,
    background?: string,
  },
};

​

Style Customization
type CustomStyle = {
  notificationIcon?: {
    size?: number,
  },
  window?: {
    width?: DimensionValue,
    borderRadius?: number,
  },
  windowHeader?: {
    height?: DimensionValue,
    titleFontWeight?: TextStyle["fontWeight"],
    titleSize?: number,
    titlePadding?: number,
    borderWidth?: string,
  },
  windowContainer?: {
    padding?: number,
    contentHeight?: DimensionValue,
  },
  customCard?: {
    padding?: number,
    borderWidth?: number,
    avatarSize?: number,
    titleFontWeight?: TextStyle["fontWeight"],
    titleSize?: number,
    subtitleFontWeight?: TextStyle['fontWeight'],
    subtitleSize?: number,
    descriptionFontWeight?: TextStyle['fontWeight'],
    descriptionSize?: number,
    dateSize?: number,
  },
  loadMoreButton?: {
    fontSize?: number,
    fontWeight?: TextStyle["fontWeight"],
  },
  badgeStyle?: {
    size?: number,
    textSize?: number,
    top?: number,
    right?: number,
  },
  deleteIcon?:{
    size?: number,
  },
  timerIcon?: {
    size?: number,
  },
  clearAllIcon?:{
    size?: number,
  }
};

​
Hooks

​
useSiren

The useSiren hook provides utility functions for modifying notifications: 
<script setup lang="ts">
import { useSiren } from "@sirenapp/vue-inbox";
const {
  markAsReadByDate,
  markAsReadById,
  deleteById,
  deleteByDate,
  markAllAsViewed
} = useSiren();
function handleMarkAsReadById(id: string) {
  markAsReadById(id);
}
function handleMarkAsReadByDate(untilDate: string) {
  markAsReadByDate(untilDate);
}
function handleDeleteById(id: string) {
  deleteById(id);
}
function handleDeleteByDate(date: string) {
  deleteByDate(date);
}
function handleMarkAllAsViewed(createdAt: string) {
  markAllAsViewed(createdAt);
}
</script>

​
useSiren Functions

FunctionParametersTypeDescription
markAsReadByDatestartDateISO date stringSets notifications as read until the given date
markAsReadByIdidstringMarks a specific notification as read
deleteByIdidstringDeletes a specific notification
deleteByDatestartDateISO date stringDeletes notifications until the given date
markAllAsViewedcreatedAtISO date stringMarks notifications as viewed until the given date

​
Example

Here’s a complete example of using the Vue.js Inbox SDK: 
<template>
  <SirenProvider
    :config="{
      userToken: 'your-user-token',
      recipientId: 'your-user-recipientId',
    }"
  >
    <SirenInbox
      :headerProps="{
        title: 'Siren Notifications',
        hideHeader: false,
        hideClearAll: true,
      }"
      :cardProps="{
        hideDelete: false,
        hideAvatar: false,
        disableAutoMarkAsRead: false
      }"
      :darkMode="isDarkMode"
      @card-click="handleCardClick"
      @error="handleError"
    >
      <template #customLoader>
        <div class="custom-loader">Loading notifications...</div>
      </template>
      <template #listEmptyComponent>
        <div class="empty-state">No notifications yet</div>
      </template>
    </SirenInbox>
  </SirenProvider>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { SirenProvider, SirenInbox } from "@sirenapp/vue-inbox";
const isDarkMode = ref(false);
function handleCardClick(notification) {
  console.log('Notification clicked:', notification);
  // Navigate to relevant page or show details
}
function handleError(error) {
  console.error('Notification error:', error);
  // Show error message to user
}
</script>
<style scoped>
.custom-loader {
  padding: 1rem;
  text-align: center;
  color: #666;
}
.empty-state {
  padding: 2rem;
  text-align: center;
  color: #999;
}
</style>

​
Troubleshooting

​
Common Issues

  1. SDK Not Initializing
    • Ensure you have wrapped your app with SirenProvider
    • Verify your userToken and recipientId are correct
    • Check the browser console for any error messages
  2. Notifications Not Displaying
    • Confirm the user has notifications in the system
    • Check your network requests for any API errors
    • Verify the user has the correct permissions
  3. Styling Issues
    • Ensure your custom styles do not conflict with the SDK’s styles
    • Check for any CSS specificity issues
    • Verify all required theme properties are provided if using custom themes