Module 4
Topic 5
Realtime
Building live, collaborative features with Supabase Realtime — database subscriptions, presence, and streams.
What Is Realtime?
Supabase Realtime is a feature that allows you to listen to database changes in real-time and build live, collaborative features into your Flutter apps. It's built on top of PostgreSQL and uses WebSockets for efficient communication.
✅ What You Can Build with Realtime
- Live Chat – Real-time message updates without polling
- Collaborative Editing – Multiple users editing the same document
- Live Dashboards – Real-time data visualization
- Presence Systems – See who's online and what they're doing
- Live Feeds – Social media feeds that update in real-time
- Game Leaderboards – Live score updates
Polling (Traditional)
- Repeated HTTP requests (every few seconds)
- Wastes bandwidth and battery
- High latency (up to the polling interval)
- More server load
- Simple to implement
WebSockets (Realtime)
- Persistent connection
- Efficient — only sends when data changes
- Instant updates (milliseconds)
- Less server load
- More complex setup
Realtime Channels
Realtime works through channels — logical groupings of subscriptions. You can subscribe to changes on specific tables or even specific rows.
lib/services/realtime_service.dart – Realtime Channels
import
'package:supabase_flutter/supabase_flutter.dart'
;
class
RealtimeService
{
final
SupabaseClient client = Supabase.instance.client;
RealtimeChannel? _channel;
// Subscribe to all changes on the 'posts' table
void
subscribeToPosts
({
void
Function(PostgresChangePayload)? onInsert,
void
Function(PostgresChangePayload)? onUpdate,
void
Function(PostgresChangePayload)? onDelete,
}) {
_channel = client.channel(
'public:posts'
)
.onPostgresChange(
PostgresChangeEvent.insert,
(payload) {
print(
'Post inserted: ${payload.newRecord}'
);
onInsert?.call(payload);
},
)
.onPostgresChange(
PostgresChangeEvent.update,
(payload) {
print(
'Post updated: ${payload.newRecord}'
);
onUpdate?.call(payload);
},
)
.onPostgresChange(
PostgresChangeEvent.delete,
(payload) {
print(
'Post deleted: ${payload.oldRecord}'
);
onDelete?.call(payload);
},
)
.subscribe();
}
// Subscribe to changes on a specific post
void
subscribeToPost
(String postId, {
void
Function(PostgresChangePayload)? onUpdate,
}) {
_channel = client.channel(
'public:posts:id=eq.$postId'
)
.onPostgresChange(
PostgresChangeEvent.update,
(payload) {
print(
'Post $postId updated: ${payload.newRecord}'
);
onUpdate?.call(payload);
},
)
.subscribe();
}
// Subscribe to comments on a specific post
void
subscribeToPostComments
(String postId, {
void
Function(PostgresChangePayload)? onInsert,
}) {
_channel = client.channel(
'public:comments:post_id=eq.$postId'
)
.onPostgresChange(
PostgresChangeEvent.insert,
(payload) {
print(
'Comment added to post $postId: ${payload.newRecord}'
);
onInsert?.call(payload);
},
)
.subscribe();
}
// Unsubscribe from all channels
void
unsubscribe
() {
_channel?.unsubscribe();
}
}
Presence System (Online Users)
Presence allows you to track who's online and what they're doing. It's perfect for chat apps, collaborative tools, and social features.
lib/services/presence_service.dart – Presence Tracking
import
'package:supabase_flutter/supabase_flutter.dart'
;
class
PresenceService
{
final
SupabaseClient client = Supabase.instance.client;
RealtimeChannel? _presenceChannel;
final
Map<String, dynamic> _onlineUsers = {};
Map
<String, dynamic>
get
onlineUsers => _onlineUsers;
void
initializePresence
(String roomId, String userId, String username) {
_presenceChannel = client.channel(
'presence:$roomId'
,
opts: const RealtimeChannelOptions(
config: PresenceConfig(
key:
'user_id'
,
),
),
);
// Track when users join
_presenceChannel!.onPresenceSync((payload) {
final
presenceState = payload.presenceState;
_onlineUsers.clear();
presenceState.forEach((key, value) {
final
user = value.first
as
Map<String, dynamic>;
_onlineUsers[key] = user;
});
});
// Track when users leave
_presenceChannel!.onPresenceDiff((diff) {
diff.leaves.forEach((key, value) {
_onlineUsers.remove(key);
});
});
// Join the presence channel
_presenceChannel!.subscribe((status) async {
if
(status ==
'SUBSCRIBED'
) {
final
presenceData = {
'user_id'
: userId,
'username'
: username,
'online_at'
: DateTime.now().toIso8601String(),
};
await
_presenceChannel!.track(presenceData);
}
});
}
void
updatePresence
({
required
String status,
required
String userId,
}) {
final
presenceData = {
'user_id'
: userId,
'status'
: status,
'last_active'
: DateTime.now().toIso8601String(),
};
_presenceChannel?.track(presenceData);
}
void
dispose
() {
_presenceChannel?.unsubscribe();
}
bool
isUserOnline
(String userId) {
return
_onlineUsers.containsKey(userId);
}
int
getOnlineCount
() {
return
_onlineUsers.length;
}
}
lib/widgets/online_users_widget.dart – Display Online Users
class
OnlineUsersWidget
extends
StatefulWidget {
final
PresenceService presenceService;
const
OnlineUsersWidget({
required
this
.presenceService, super.key});
@override
State<OnlineUsersWidget>
createState
() => _OnlineUsersWidgetState();
}
class
_OnlineUsersWidgetState
extends
State<OnlineUsersWidget> {
late
PresenceService _presenceService;
@override
void
initState
() {
super
.initState();
_presenceService = widget.presenceService;
}
@override
Widget
build
(BuildContext context) {
final
users = _presenceService.onlineUsers;
final
count = _presenceService.getOnlineCount();
return
Container(
padding: EdgeInsets.all(
16
),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
'🟢 $count online'
,
style: TextStyle(fontWeight: FontWeight.bold),
),
SizedBox(height:
8
),
Wrap(
spacing:
8
,
runSpacing:
8
,
children: users.entries.map((entry) {
final
user = entry.value
as
Map<String, dynamic>;
return
Chip(
avatar: CircleAvatar(
radius:
12
,
child: Text(
(user[
'username'
] ??
'?'
)[
0
].toUpperCase(),
style: TextStyle(fontSize:
10
),
),
),
label: Text(user[
'username'
] ??
'Unknown'
),
backgroundColor: Colors.green.shade50,
);
}).toList(),
),
],
),
);
}
}
Streams and Subscriptions
You can convert Realtime subscriptions into Dart Streams for easy integration with Flutter's reactive programming model.
lib/services/stream_service.dart – Realtime Streams
import
'dart:async'
;
import
'package:supabase_flutter/supabase_flutter.dart'
;
class
StreamService
{
final
SupabaseClient client = Supabase.instance.client;
RealtimeChannel? _channel;
final
StreamController<List<Map<String, dynamic>>> _messagesController =
StreamController<List<Map<String, dynamic>>>.broadcast();
Stream<List<Map<String, dynamic>>>
get
messagesStream => _messagesController.stream;
void
subscribeToMessages
(String roomId) {
_channel = client.channel(
'public:messages:room_id=eq.$roomId'
)
.onPostgresChange(
PostgresChangeEvent.insert,
(payload) {
// Get current messages from the database
_fetchCurrentMessages(roomId);
},
)
.onPostgresChange(
PostgresChangeEvent.update,
(payload) {
_fetchCurrentMessages(roomId);
},
)
.onPostgresChange(
PostgresChangeEvent.delete,
(payload) {
_fetchCurrentMessages(roomId);
},
)
.subscribe();
// Initial fetch
_fetchCurrentMessages(roomId);
}
Future
<
void
>
_fetchCurrentMessages
(String roomId) async {
try
{
final
response =
await
client
.from(
'messages'
)
.select(
'*, profiles(username)'
)
.eq(
'room_id'
, roomId)
.order(
'created_at'
, ascending:
true
);
_messagesController.add(response);
}
catch
(e) {
print(
'Error fetching messages: $e'
);
}
}
void
dispose
() {
_channel?.unsubscribe();
_messagesController.close();
}
}
// Using the stream with Riverpod
final
messagesStreamProvider = StreamProvider<List<Map<String, dynamic>>>((ref) {
final
service = ref.watch(streamServiceProvider);
return
service.messagesStream;
});
Complete Example: Live Chat App
Here's a complete live chat app using Supabase Realtime for instant message updates.
lib/main.dart – Complete Chat App
import
'package:flutter/material.dart'
;
import
'package:supabase_flutter/supabase_flutter.dart'
;
import
'package:intl/intl.dart'
;
void
main
() async {
await
Supabase.initialize(
url:
'https://your-project.supabase.co'
,
anonKey:
'your-anon-key'
,
);
runApp(
MyApp
());
}
class
MyApp
extends
StatelessWidget {
@override
Widget
build
(BuildContext context) {
return
MaterialApp(
title:
'Live Chat'
,
theme: ThemeData(
colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
useMaterial3:
true
,
),
home: ChatRoomScreen(),
);
}
}
// ==========================================
// 1. CHAT SERVICE
// ==========================================
class
ChatService
{
final
SupabaseClient client = Supabase.instance.client;
RealtimeChannel? _channel;
final
List<Map<String, dynamic>> _messages = [];
final
List<Function> _listeners = [];
List
<Map<String, dynamic>>
get
messages => _messages;
void
addListener
(Function listener) {
_listeners.add(listener);
}
void
removeListener
(Function listener) {
_listeners.remove(listener);
}
void
_notifyListeners
() {
for
(
var
listener
in
_listeners) {
listener();
}
}
Future
<
void
>
connect
(String roomId) async {
// Load initial messages
await
_loadMessages(roomId);
// Subscribe to real-time updates
_channel = client.channel(
'public:messages:room_id=eq.$roomId'
)
.onPostgresChange(
PostgresChangeEvent.insert,
(payload) async {
// Check if the new message belongs to this room
final
newRecord = payload.newRecord
as
Map<String, dynamic>;
if
(newRecord[
'room_id'
] == roomId) {
// Fetch the full message with user profile
final
fullMessage =
await
client
.from(
'messages'
)
.select(
'*, profiles(username)'
)
.eq(
'id'
, newRecord[
'id'
])
.single();
_messages.add(fullMessage);
_notifyListeners();
}
},
)
.subscribe();
}
Future
<
void
>
_loadMessages
(String roomId) async {
final
response =
await
client
.from(
'messages'
)
.select(
'*, profiles(username)'
)
.eq(
'room_id'
, roomId)
.order(
'created_at'
, ascending:
true
);
_messages.clear();
_messages.addAll(response);
_notifyListeners();
}
Future
<
void
>
sendMessage
({
required
String roomId,
required
String userId,
required
String content,
}) async {
if
(content.trim().isEmpty)
return
;
await
client.from(
'messages'
).insert({
'room_id'
: roomId,
'user_id'
: userId,
'content'
: content.trim(),
});
}
void
disconnect
() {
_channel?.unsubscribe();
_listeners.clear();
}
}
// ==========================================
// 2. CHAT UI
// ==========================================
class
ChatRoomScreen
extends
StatefulWidget {
@override
State<ChatRoomScreen>
createState
() => _ChatRoomScreenState();
}
class
_ChatRoomScreenState
extends
State<ChatRoomScreen> {
final
ChatService _chatService = ChatService();
final
TextEditingController _messageController = TextEditingController();
final
ScrollController _scrollController = ScrollController();
String _roomId =
'general'
;
@override
void
initState
() {
super
.initState();
_chatService.addListener(_updateUI);
_connectToChat();
}
@override
void
dispose
() {
_chatService.removeListener(_updateUI);
_chatService.disconnect();
_messageController.dispose();
_scrollController.dispose();
super
.dispose();
}
void
_updateUI
() {
setState(() {});
_scrollToBottom();
}
void
_scrollToBottom
() {
WidgetsBinding.instance.addPostFrameCallback((_) {
if
(_scrollController.hasClients) {
_scrollController.animateTo(
_scrollController.position.maxScrollExtent,
duration: Duration(milliseconds:
300
),
curve: Curves.easeOut,
);
}
});
}
Future
<
void
>
_connectToChat
() async {
await
_chatService.connect(_roomId);
setState(() {});
_scrollToBottom();
}
Future
<
void
>
_sendMessage
() async {
final
user = Supabase.instance.client.auth.currentUser;
if
(user ==
null
)
return
;
await
_chatService.sendMessage(
roomId: _roomId,
userId: user.id,
content: _messageController.text,
);
_messageController.clear();
}
@override
Widget
build
(BuildContext context) {
final
messages = _chatService.messages;
final
user = Supabase.instance.client.auth.currentUser;
return
Scaffold(
appBar: AppBar(
title: Row(
children: [
Container(
width:
10
,
height:
10
,
decoration: BoxDecoration(
shape: BoxShape.circle,
color: Colors.green,
),
),
SizedBox(width:
8
),
Text(
'#$_roomId'
),
],
),
centerTitle:
true
,
),
body: Column(
children: [
Expanded(
child: messages.isEmpty
? Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
Icon(Icons.chat_bubble_outline, size:
80
, color: Colors.grey.shade400),
SizedBox(height:
16
),
Text(
'No messages yet'
,
style: TextStyle(fontSize:
20
, fontWeight: FontWeight.w600),
),
Text(
'Be the first to send a message!'
,
style: TextStyle(color: Colors.grey.shade400),
),
],
),
)
: ListView.builder(
controller: _scrollController,
padding: EdgeInsets.all(
12
),
itemCount: messages.length,
itemBuilder: (context, index) {
final
message = messages[index];
final
profile = message[
'profiles'
]
as
Map<String, dynamic>?;
final
username = profile?[
'username'
] ??
'Unknown'
;
final
isMe = message[
'user_id'
] == user?.id;
final
createdAt = DateTime.parse(message[
'created_at'
]);
return
Align(
alignment: isMe ? Alignment.centerRight : Alignment.centerLeft,
child: Container(
margin: EdgeInsets.only(bottom:
8
),
constraints: BoxConstraints(
maxWidth: MediaQuery.of(context).size.width *
0.75
,
),
child: Column(
crossAxisAlignment: isMe ? CrossAxisAlignment.end : CrossAxisAlignment.start,
children: [
Row(
mainAxisSize: MainAxisSize.min,
children: [
if
(!isMe)
CircleAvatar(
radius:
12
,
child: Text(
username.isNotEmpty ? username[
0
].toUpperCase() :
'?'
,
style: TextStyle(fontSize:
10
),
),
),
SizedBox(width:
4
),
Text(
isMe ?
'You'
: username,
style: TextStyle(
fontSize:
12
,
fontWeight: FontWeight.w600,
color: isMe ? Colors.deepPurple : Colors.grey.shade700,
),
),
],
),
Container(
padding: EdgeInsets.all(
12
),
decoration: BoxDecoration(
color: isMe
? Colors.deepPurple.shade50
: Colors.grey.shade100,
borderRadius: BorderRadius.circular(
12
),
),
child: Text(message[
'content'
]),
),
Text(
DateFormat('h:mm a').format(createdAt),
style: TextStyle(
fontSize:
10
,
color: Colors.grey.shade500,
),
),
],
),
),
);
},
),
),
// Input bar
Container(
padding: EdgeInsets.all(
12
),
decoration: BoxDecoration(
color: Colors.grey.shade50,
border: Border(top: BorderSide(color: Colors.grey.shade200)),
),
child: Row(
children: [
Expanded(
child: TextField(
controller: _messageController,
decoration: InputDecoration(
hintText:
'Type a message...'
,
border: OutlineInputBorder(
borderRadius: BorderRadius.circular(
24
),
),
contentPadding: EdgeInsets.symmetric(horizontal:
16
, vertical:
8
),
),
onSubmitted: (_) => _sendMessage(),
),
),
SizedBox(width:
8
),
IconButton(
icon: Icon(Icons.send, color: Colors.deepPurple),
onPressed: _sendMessage,
),
],
),
),
],
),
);
}
}
Step-by-Step Explanation
1.
Enable Realtime
– In Supabase Dashboard, enable Realtime for the tables you want to listen to.
2.
Create a channel
– Use
client.channel('public:table_name')
to create a Realtime channel.
3.
Listen to events
– Use
.onPostgresChange()
to listen to INSERT, UPDATE, DELETE events.
4.
Subscribe
– Call
.subscribe()
to start receiving real-time updates.
5.
Update UI
– When a change is received, update your UI using setState or StreamBuilder.
Best Practices
✅ Do's
- Always unsubscribe from channels when leaving a screen
- Use filters to only listen to relevant data (e.g., specific room)
- Handle reconnection logic for network interruptions
- Use StreamBuilder or ValueListenableBuilder for reactive UI
- Limit the number of channels to avoid performance issues
❌ Don'ts
- Don't forget to dispose streams and channels
- Don't listen to all tables — only subscribe to what you need
- Don't rely on Realtime for critical data consistency (use transactions)
Common Mistakes
❌ Mistake 1: Not enabling Realtime in the dashboard
Realtime must be enabled for each table in the Supabase Dashboard. Without this, subscriptions won't work.
✅ Correct: Enable Realtime for your tables
Go to Database → Replication and enable Realtime for the tables you need.
❌ Mistake 2: Not unsubscribing from channels
Leaving channels open can cause memory leaks and unnecessary network usage.
✅ Correct: Always unsubscribe
Call
channel.unsubscribe()
in
dispose()
or when navigating away.
❌ Mistake 3: Not handling connection errors
Network issues can cause Realtime connections to drop. Handle reconnection gracefully.
✅ Correct: Handle reconnection
Use the
onReconnection
callback or listen to the connection status.
🎯 Key Takeaway
Supabase Realtime enables live, collaborative features in your Flutter apps. Use channels to subscribe to database changes, presence to track online users, and streams for reactive programming. Always enable Realtime in the dashboard and unsubscribe from channels when done.