Repository files navigation

Easy to usechat API/Server with scalable infrastructure

• Compatible with all Javascript frameworks (Vue, Angular, React, etc.) or no framework at all
• Customizeable realtime chat messaging
• Backend agnostic
• Images, videos, files, voice messages & emojis
• Edit messages & reply to other messages
• Tag users & emojis shortcut suggestions
• UI elements for seen, new, deleted, typing and system messages
• Text formatting - bold, italic, strikethrough, underline, code, multiline
• Online / Offline users status
• Flexible options and slots
• Light and dark theme modes
• Firestore example
• Typescript, PWA, Web Component support

Enjoy 😄

A Progressive Web Application showcasing all the features ofvue-advanced-chat component.
Built with Firestore, Vuetify, and Push Notifications.

If you wish to get premium access to the real world example source code, please contact me by email.

You will get a fully working chat application for web and mobile:

• UI and backend integration
• Email, Facebook and Google authentication
• Real-time messaging, browser push notifications, images optimization (Firebase Cloud Functions to compress avatars)
• UI/UX components for alerts (errors, information), dialogs, etc.
• Add existing users to a room using their email
• Send email invitations to non-existing users
• Edition of profile and rooms
• Addition and deletion of room users
• Optimised firestore implementation to reduce bandwidth and costs as much as possible
• State management using vuex
• Internationalisation (i18n)
• Google Analytics
• Support to help you get the chat up and running

• Installation
• Usage
• Props API
• Props data structure
• Events API
• Named Slots
• Using with Firestore

# Using npmnpm install --save vue-advanced-chat# Using yarnyarn add vue-advanced-chat# Using CDN<script src="https://cdn.jsdelivr.net/npm/vue-advanced-chat@2.0.4/dist/vue-advanced-chat.umd.js"></script>

Registervue-advanced-chat andemoji-picker as web components in yourconfig file:

compilerOptions:{isCustomElement:tagName=>{returntagName==='vue-advanced-chat'||tagName==='emoji-picker'}}

Demo:https://github.com/advanced-chat/vue-advanced-chat-sandbox/tree/main

Demo:https://github.com/advanced-chat/vue-advanced-chat-sandbox/tree/react

Demo:https://github.com/advanced-chat/vue-advanced-chat-sandbox/tree/angular

<template><vue-advanced-chat    :current-user-id="currentUserId"    :rooms="JSON.stringify(rooms)"    :messages="JSON.stringify(messages)"    :room-actions="JSON.stringify(roomActions)"/></template><script>  import{register} from 'vue-advanced-chat'  register()  // Or if you used CDN import  // window['vue-advanced-chat'].register()  export default{data(){return{currentUserId:'1234',rooms:[],messages:[],roomActions:[{name:'inviteUser',title:'Invite User'},{name:'removeUser',title:'Remove User'},{name:'deleteRoom',title:'Delete Room'}]}}}</script>

vue-advanced-chat component is performance oriented, hence you have to follow specific rules to make it work properly.

• Use array assignement instead ofpush method

// DO THISconstrooms=[]for(leti=0;i<res.length;i++){rooms.push(res)}this.rooms=rooms// DON'T DO THISfor(leti=0;i<res.length;i++){this.rooms.push(res)}

// DO THISthis.rooms[i].typingUsers=[...this.rooms[i].typingUsers,typingUserId]// DON'T DO THISthis.rooms[i].typingUsers.push(typingUserId)

• To add or replace an item inside an array, use spread operator

// DO THISthis.rooms[roomIndex]=roomthis.rooms=[...this.rooms]// DON'T DO THISthis.rooms[roomIndex]=room// AND DON'T DO THISthis.rooms.push(room)

• Follow the UI loading pattern by updatingmessagesLoaded prop every time a new room is fetched

fetchMessages({ room, options}){this.messagesLoaded=false// use timeout to imitate async server fetched datasetTimeout(()=>{this.messages=[]this.messagesLoaded=true})}

If you are using Vue 3, you can pass Array and Object props normally:Passing DOM Properties in Vue 3
Otherwise, you need to pass those props as strings. For example:[messages]="JSON.stringify(messages)"

(1)current-user-id is required to display UI and trigger actions according to the user using the chat (ex: messages position on the right, etc.)

(2)loading-rooms can be used to show/hide a spinner icon while rooms are loading

(3)rooms-loaded must be set totrue when all rooms have been loaded. Meaning the user cannot scroll to load more paginated rooms

(4)room-id can be used to load a specific room at any time

(5)load-first-room can be used to remove the default behaviour of opening the first room at initialization

(6)custom-search-room-enabled can be used to use thesearch-room event to call your own method to filter out rooms

(7)room-message can be used to add a default textarea value

(8)username-options can be used to show/hide room messages username according to the minimum number of usersminUsers inside a room, and if the message user is the current usercurrentUser

(9)messages-loaded must be set totrue when all messages of a conversation have been loaded. Meaning the user cannot scroll on top to load more paginated messages

(10)room-actions can be used to display your own buttons when clicking the dropdown icon of each room inside the rooms list.
You can then use theroom-action-handler event to call your own action after clicking a button. Ex:

room-actions="[{name:'archiveRoom',title:'Archive Room'}]"

(11)menu-actions can be used to display your own buttons when clicking the vertical dots icon inside a room.
You can then use themenu-action-handler event to call your own action after clicking a button. Ex:

menu-actions="[{name:'inviteUser',title:'Invite User'},{name:'removeUser',title:'Remove User'},{name:'deleteRoom',title:'Delete Room'}]"

(12)message-actions can be used to display your own buttons when clicking the dropdown icon inside a message.
You can then use themessage-action-handler event to call your own action after clicking a button. Ex:

message-actions="[{name:'addMessageToFavorite',title:'Add To Favorite'},{name:'shareMessage',title:'Share Message'}]"

You can use built-inmessage-actions names to trigger specific UI modifications when clicked.
Currently,replyMessage,editMessage anddeleteMessage action names are available.
IfmessageActions is not set, it will use the default values below.
If you don't want to display thismessageActions menu, you can pass it an empty array.

messageActions="[{name:'replyMessage',title:'Reply'},{name:'editMessage',title:'Edit Message',onlyMe:true},{name:'deleteMessage',title:'Delete Message',onlyMe:true},{name:'selectMessages',title:'Select'}]"

(13)message-selection-actions is related to the aboveselectMessages message action. You can use it to display custom action buttons in the room header when selecting a message. Ex:

messageActions="[  {    name: 'deleteMessages',    title: 'Delete'  },  {    name: 'forwardMessages',    title: 'Forward'  }]"

(14)templates-text can be used to add autocomplete templates text when typing/ in the room textarea. Ex:

templatesText="[{tag:'help',text:'This is the help'},{tag:'action',text:'This is the action'}]"

(15)auto-scroll can be used to change the auto scroll behaviour when sending/receiving a message. Ex:

auto-scroll="{send:{new:true,// will scroll down after sending a messagenewAfterScrollUp:false// will not scroll down after sending a message when scrolled up},receive:{new:false,// will not scroll down when receiving a messagenewAfterScrollUp:true// will scroll down when receiving a message when scrolled up}}"

(16)show-new-messages-divider can be used to show/hide the blue line divider between seen and unseen messages.

(17)show-footer can be used to hide the room footer. For example to prevent users to send any message or media.

(18)text-messages can be used to replace default i18n texts. Ex:

text-messages="{ROOMS_EMPTY:'Aucune conversation',ROOM_EMPTY:'Aucune conversation sélectionnée',NEW_MESSAGES:'Nouveaux messages',MESSAGE_DELETED:'Ce message a été supprimé',MESSAGES_EMPTY:'Aucun message',CONVERSATION_STARTED:'La conversation a commencée le :',TYPE_MESSAGE:'Tapez votre message',SEARCH:'Rechercher',IS_ONLINE:'est en ligne',LAST_SEEN:'dernière connexion ',IS_TYPING:'est en train de taper...',CANCEL_SELECT_MESSAGE:'Annuler Sélection'}"

(19)text-formatting can be used to add text formatting. Bold, italic, strikethrough, underline, inline code and multiline code formatting are currently available and can be used in conjonction.

• You can disable text formatting by passing the prop:text-formatting="{disabled: true}".
• You can change markdown characters, for example::text-formatting="{italic: '^'}"
• You can disable a specific markdown character, for example::text-formatting="{bold: null}"

Inline Code

Example: `This is inline code`

Output:This is inline code

Multiline Code

Example: ```This is multiline code```

Output:

This ismultiline code

(20)link-options can be used to disable url links in messages, or change urls target. Ex:

:link-options="{ disabled: true, target: '_self', rel: null }"

(21)room-info-enabled can be used to trigger an event after clicking the room header component.
You can then use theroom-info event to call your own action after clicking the header.

(22)textarea-action-enabled can be used to add an extra icon on the right of the textarea
You can then use thetextarea-action-handler event to call your own action after clicking the icon.

(23)responsive-breakpoint can be used to collapse the rooms list on the left when then viewport size goes below the specified width.

(24)single-room can be used if you never want to show the rooms list on the left. You still need to pass therooms prop as an array with a single element.

(25)scroll-distance can be used to change the number of pixels beforefetchMessages event is triggered when scrolling up to load more messages, orfetchMoreRooms event is triggered when scrolling down to load more rooms.

(26)theme can be used to change the chat theme. Currently, onlylight anddark are available.

(27)accepted-files can be used to set specifics file types allowed in chat. By default, all file types are allowed:"*".

Example: setaccepted-files="image/png, image/jpeg, application/pdf" to allowJPGPNG andPDF files only

(28)capture-files can be used to enable direct capturing of photos and videos on mobile browsers, as opposed to just uploading existing photos and videos which are already on the device. Seehere for more information and recognized values. By default, the attribute is omitted and mobile browsers will only offer the gallery to choose photos and videos. Note: this only affects file attachments. Audio messages are always recorded using the device's microphone.

(29)multiple-files can be used to define whether multiple file selections will be accepted. By default this is true.

(30)styles can be used to customize your own theme. You can find the full listhere

(31)show-audio can be used to enable or disable audio icon

styles="{general:{color:'#0a0a0a',colorSpinner:'#333',borderStyle:'1px solid #e1e4e8'},footer:{background:'#f8f9fa',backgroundReply:'rgba(0, 0, 0, 0.08)'},icons:{    search:'#9ca6af'}}"

Your props must follow a specific structure to display rooms and messages correctly:

rooms="[{roomId:'1',roomName:'Room 1',avatar:'assets/imgs/people.png',unreadCount:4,index:3,lastMessage:{_id:'xyz',content:'Last message received',senderId:'1234',username:'John Doe',timestamp:'10:20',saved:true,distributed:false,seen:false,new:true},users:[{_id:'1234',username:'John Doe',avatar:'assets/imgs/doe.png',status:{state:'online',lastChanged:'today, 14:30'}},{_id:'4321',username:'John Snow',avatar:'assets/imgs/snow.png',status:{state:'offline',lastChanged:'14 July, 20:00'}}],typingUsers:[4321]}]"

• If you add theindex property, your rooms will be ordered using this value.index can be any sortable value, like astring,datetime,timestamp, etc.

• For each room user, you can add thestatus property, which can hold thestate andlastChanged properties:

  • state can be'online' or'offline'
  • lastChanged is the date whenstate was last modified.

• typingUsers is an array of all the users who are currently writing a message

Message objects are rendered differently depending on their type. Text, emoji, image, video and file types are supported.

Each message object has asenderId field which holds the id of the corresponding agent. IfsenderId matches thecurrentUserId prop, specific UI and actions will be implemented.

Notes:

• username will be displayed on each message of corresponding agents if at least 3 users are in the room
• system is used to show messages with a specific centered display
• indexId can be used if you need to change a message ID that is already displayed in a room, this preventing an animation glitch. For example, when you don't know in advance the message ID your backend will create.

Message states:

• saved: true one checkmark
• distributed: true two checkmarks
• seen: true two blue checkmarks
• deleted: true grey background with deleted message text
• failure: true red clickable failure icon

messages="[{_id:'7890',indexId:12092,content:'Message 1',senderId:'1234',username:'John Doe',avatar:'assets/imgs/doe.png',date:'13 November',timestamp:'10:20',system:false,saved:true,distributed:true,seen:true,deleted:false,failure:true,disableActions:false,disableReactions:false,files:[{name:'My File',size:67351,type:'png',audio:true,duration:14.4,url:'https://firebasestorage.googleapis.com/...',preview:'data:image/png;base64,iVBORw0KGgoAA...',progress:88}],reactions: {😁:['1234',// USER_ID'4321'],🥰:['1234']},replyMessage:{content:'Reply Message',senderId:'4321',files:[{name:'My Replied File',size:67351,type:'png',audio:true,duration:14.4,url:'https://firebasestorage.googleapis.com/...',preview:'data:image/png;base64,iVBORw0KGgoAA...'}]},}]"

(1)fetch-messages is triggered every time a room is opened. If the room is opened for the first time, theoptions param will holdreset: true.
(1)fetch-messages should be a method implementing a pagination system. Its purpose is to load older messages of a conversation when the user scroll on top.

(2)fetch-more-rooms is triggered when scrolling down the rooms list, and should be a method implementing a pagination system.

(3)open-user-tag is triggered when clicking a user tag inside a message. When creating a user tag by typing@ in the footer textarea and sending the message, the tag will be identified with the below pattern:

<usertag>TAGGED_USER_ID</usertag>

This will make the tag clickable inside a message. Ex:message tag content
send-message andedit-message events will handle that pattern for you and pass it in thecontent param.

(4)room-action-handler is the result of theroom-actions prop.
When clicking a button from yourroom-actions array,room-action-handler will give you the name of the button that was click.Then you can do anything you want with it. Ex:

menuActionHandler({ roomId, action}){switch(action.name){case'archiveRoom':// call a method to archive the room}}

(5)menu-action-handler is the result of themenu-actions prop.
When clicking a button from yourmenu-actions array,menu-action-handler will give you the name of the button that was click.Then you can do anything you want with it. Ex:

menuActionHandler({ roomId, action}){switch(action.name){case'inviteUser':// call a method to invite a user to the roomcase'removeUser':// call a method to remove a user from the roomcase'deleteRoom':// call a method to delete the room}}

(6)search-room can be enabled by usingcustom-search-room-enabled prop. This will allow you to call your own method to filter out searched rooms.

(7)message-action-handler is the result of themessage-actions prop.
When clicking a button from yourmessage-actions array,message-action-handler will give you the name of the button that was click and the corresponding message data.Then you can do anything you want with it. Ex:

messageActionHandler({ roomId, action, message}){switch(action.name){case'addMessageToFavorite':// call a method to add a message to the favorite listcase'shareMessage':// call a method to share the message with another user}}

(8)message-selection-action-handler is the result of themessage-selection-actions prop.
When clicking a button from yourmessage-selection-actions array,message-selection-action-handler will give you the name of the button that was click and the corresponding selected messages data.Then you can do anything you want with it. Ex:

messageSelectionActionHandler({ roomId, action, message}){switch(action.name){case'deleteMessages':// call a method to delete selected messagedcase'shareMessage':// call a method to share selected messaged with another user}}

(9)room-info is the result of theroom-info-enabled prop.

(10)textarea-action-handler is the result of thetextarea-action-enabled prop.

(11) Array of files where each file contain:{ blob, localUrl, name, size, type, extension }

(12)replyMessage object is available when the user replied to another message by clicking the corresponding icon, and contains the message information that was clicked.

Example:

<vue-advanced-chat><divslot="room-header">    This is a new room header</div><divv-for="message in messages" :slot="'message_' + message._id"><divv-if="message.system">      System message:{{message.content}}</div><divv-else>      Normal message:{{message.content}}</div></div><divv-for="message in messages" :slot="'message-avatar_' + message._id">    New Avatar</div></vue-advanced-chat>

You can find the source code to implement a full featured chat app using Firebase/Firestore inside thedemo folder.
To test it using your own Firebase project:

• Setup Cloud Firestore (to store users and rooms) and Realtime Database (to store users online status)
• Clone this repository:git clone https://github.com/advanced-chat/vue-advanced-chat.git
• Insidedemo/src/database/index.js file, replace the lineconst config = ... by your own Firebase config
• Go insidedemo folder and runnpm run serve

If you decide to use the same code as in thedemo folder to create your chat app, you need to have a specific Firestore data structure.
To help you get started, I added indemo/src/App.vue a methodaddData to initialize some data on your Firestore database.

users:{USER_ID_1:{_id:'1',username:'User 1'},USER_ID_2:{_id:'2',username:'User 2'},USER_ID_3:{_id:'3',username:'User 2'}}

chatRooms:{ROOM_ID_1:{users:['1','3']},ROOM_ID_2:{users:['1','2','3']}}

messages:{MESSAGE_ID_1:{content:'My first message to <usertag>John</usertag>',senderId:'2',timestamp:'December 11, 2019 at 4:00:00 PM',seen:true}}

• You need to create a composite index to order rooms by last message received.The easiest way to do it is to create a room, then click the error message url in the browser debugging console.

Your help is always appreciated 🚀

This project is licensed underMIT License