Supabase Realtime × Flutter — Complete Guide to Real-Time Sync Patterns

"Save and see it instantly" is table stakes for modern apps. Supabase Realtime makes it straightforward.

Broadcast: Lightweight Instant Notifications

// Create a channel and send/receive Broadcasts
final channel = supabase.channel('room-1');

channel
  .onBroadcast(
    event: 'cursor',
    callback: (payload) {
      final x = payload['x'] as double;
      final y = payload['y'] as double;
      setState(() => _remoteCursor = Offset(x, y));
    },
  )
  .subscribe();

// Send your own cursor position
Future<void> sendCursor(Offset pos) async {
  await channel.sendBroadcast(
    event: 'cursor',
    payload: {'x': pos.dx, 'y': pos.dy},
  );
}

Use cases: cursor sharing, typing indicators, transient event notifications (nothing that needs DB persistence)

Presence: Syncing Online Status

// Track who's online with Presence
final presenceChannel = supabase.channel('online-users');

presenceChannel
  .onPresenceSync(callback: (payload) {
    // Get everyone's current state
    final state = presenceChannel.presenceState();
    setState(() {
      _onlineUsers = state.values
          .expand((list) => list)
          .map((p) => p.payload['user'] as String)
          .toList();
    });
  })
  .subscribe(
    (status, [_]) async {
      if (status == RealtimeSubscribeStatus.subscribed) {
        // Announce your own presence
        await presenceChannel.track({'user': _userId, 'status': 'active'});
      }
    },
  );

@override
void dispose() {
  presenceChannel.untrack();
  supabase.removeChannel(presenceChannel);
  super.dispose();
}

Postgres Changes: Receive DB Mutations in Real Time

// Subscribe to changes on the tasks table
supabase
  .channel('tasks-changes')
  .onPostgresChanges(
    event: PostgresChangeEvent.all,
    schema: 'public',
    table: 'tasks',
    filter: PostgresChangeFilter(
      type: PostgresChangeFilterType.eq,
      column: 'user_id',
      value: _userId,
    ),
    callback: (payload) {
      switch (payload.eventType) {
        case PostgresChangeEvent.insert:
          final task = Task.fromJson(payload.newRecord);
          setState(() => _tasks.add(task));
        case PostgresChangeEvent.update:
          final updated = Task.fromJson(payload.newRecord);
          setState(() {
            final idx = _tasks.indexWhere((t) => t.id == updated.id);
            if (idx >= 0) _tasks[idx] = updated;
          });
        case PostgresChangeEvent.delete:
          final id = payload.oldRecord['id'] as String;
          setState(() => _tasks.removeWhere((t) => t.id == id));
        default:
          break;
      }
    },
  )
  .subscribe();

Optimistic Update Pattern

// Update the UI first, then sync to DB (improves perceived performance)
Future<void> toggleTask(Task task) async {
  // 1. Optimistic update (instant)
  setState(() {
    final idx = _tasks.indexWhere((t) => t.id == task.id);
    _tasks[idx] = task.copyWith(completed: !task.completed);
  });

  try {
    // 2. Persist to DB
    await supabase
        .from('tasks')
        .update({'completed': !task.completed})
        .eq('id', task.id);
    // Realtime receives the change — UI is already in the correct state
  } catch (e) {
    // 3. Roll back on failure
    setState(() {
      final idx = _tasks.indexWhere((t) => t.id == task.id);
      _tasks[idx] = task;  // restore original
    });
  }
}

Summary

Broadcast        → Transient events with no DB persistence (cursor, typing)
Presence         → Online status and session management
Postgres Changes → Subscribe to DB mutations (filter to your own data)
Optimistic UI    → Update state first to maximize perceived speed

Realtime channels carry a connection cost — only open the ones you need, and always release them in dispose.