Documentation Index
Fetch the complete documentation index at: https://docs.trysiren.io/llms.txt
Use this file to discover all available pages before exploring further.
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
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>
<template>
<SirenInbox />
</template>
<script setup lang="ts">
import { SirenInbox } from "@sirenapp/vue-inbox";
</script>
Inbox Props
| Prop | Description | Type | Default |
|---|
theme | Object for custom themes | Theme | {} |
customStyles | Object for custom styling | CustomStyle | {} |
loadMoreLabel | Text shown on the load more component | string | ”Load More” |
hideBadge | Toggle to hide or show the badge | boolean | false |
darkMode | Toggle to enable dark mode | boolean | false |
itemsPerFetch | Number of notifications per API request (max 50) | number | 20 |
windowViewOnly | Toggle for fit-to-screen window or modal view | boolean | false |
headerProps | Props for customizing the header | HeaderProps | { title: 'Notifications', hideHeader: false, hideClearAll: false } |
cardProps | Props for customizing notification cards | CardProps | { hideDelete: false, hideAvatar: false, disableAutoMarkAsRead: false, onAvatarClick: ()=>null } |
onCardClick | Click handler for notification cards | (notification) => void | () => null |
onError | Error handler | (error: SirenErrorType) => void | () => null |
CardProps
type CardProps = {
hideDelete?: boolean;
hideAvatar?: boolean;
onAvatarClick?: (notification: NotificationDataType) => void;
disableAutoMarkAsRead?: boolean;
};
type HeaderProps = {
title?: string;
hideHeader?: boolean;
hideClearAll?: boolean;
};
Inbox Slots
Customize components using these slots:
| Slot | Description |
|---|
loadMoreComponent | Custom load more button component |
customHeader | Custom header component |
customLoader | Custom loader component |
customErrorWindow | Custom error window |
listEmptyComponent | Custom empty list component |
customCard | Custom notification card component |
customFooter | Custom footer component |
notificationIcon | Custom notification icon component |
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,
},
};
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
| Function | Parameters | Type | Description |
|---|
markAsReadByDate | startDate | ISO date string | Sets notifications as read until the given date |
markAsReadById | id | string | Marks a specific notification as read |
deleteById | id | string | Deletes a specific notification |
deleteByDate | startDate | ISO date string | Deletes notifications until the given date |
markAllAsViewed | createdAt | ISO date string | Marks 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
- 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
- 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
- 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
