---
name: bijection-convex-unread-tracking
description: "Evaluate and integrate the Unread Tracking component with Bijection."
---

# Unread Tracking

Real-time unread message counter and read     receipt tracker with watermark-based read     positions, bulk subscriptions, and React hooks.

This is an upstream package. It has not been adapted or qualified for Bijection.

- Package: convex-unread-tracking
- Source: https://github.com/TimpiaAI/convex-unread-tracking
- npm: https://www.npmjs.com/package/convex-unread-tracking
- Directory: https://bijection.com/components/convex-unread-tracking

Read the upstream README for setup, license, and compatibility before using it.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes convex-unread-tracking. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


# Unread Tracking

## Instructions

Use Unread Tracking to real-time unread message counter and read receipt tracker for convex with watermark-based read positions and react hooks. This Convex component integrates directly with your backend.

### Installation

```bash
npm install convex-unread-tracking
```

### Capabilities

- Track read positions per user per channel with automatic unread counting
- Manage bulk subscriptions and group operations for team messaging apps
- Get optimistic mark-as-read with localStorage offline support via React hooks
- Clean up old tracking data automatically with built-in cron utilities

## Examples

### how to track unread messages in Convex chat app

Use convex-unread-tracking to register messages with insertMessage() when sent, then call getUnreadCount() to get real-time unread counts per channel. The component tracks read positions using watermarks and provides automatic cleanup via crons.

### Convex read receipts and message tracking

The component provides markReadUpTo() for watermark-based read tracking and getLastRead() for scroll anchoring. It supports explicit range overrides with markReadRange() and single message unread marking with markOneUnread().

### bulk message subscriptions Convex teams

Use group operations like addToGroup() and subscribeAll() to manage team-wide channel subscriptions. The component supports muting senders with muteSender() and archiving entire channels with archive().

### optimistic UI unread messages React Convex

The useMarkAsRead and useOptimisticUnreadCount hooks provide immediate UI feedback when marking messages as read, with localStorage fallback for offline scenarios. Call markRead() optimistically, then confirmRead() after server sync.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Unread Tracking is not needed

## Troubleshooting

**How does the watermark system work for read tracking?**

The convex-unread-tracking component uses timestamps as watermarks to mark everything up to a specific time as read via markReadUpTo(). You can override this with explicit ranges using markReadRange() or mark individual messages unread with markOneUnread().

**Can I track unread counts across multiple channels at once?**

Yes, convex-unread-tracking provides getTotalUnreadCount() for aggregate counts across all user subscriptions and getSingleUnreads() for batch fetching per-channel counts. Both methods work with the subscription management system.

**How do I handle team-wide channel subscriptions?**

Use the group operations in convex-unread-tracking: addToGroup() to add users to a group, then subscribeAll() or unsubscribeAll() to manage entire team subscriptions to channels in bulk operations.

**Does this component handle message cleanup automatically?**

Yes, convex-unread-tracking includes a cleanup mutation designed for Convex cron jobs. Set up a daily cron to automatically garbage collect old tracking data and maintain database performance.

**How do the React hooks handle offline scenarios?**

The convex-unread-tracking React hooks use localStorage to persist optimistic state when offline. Call markRead() for immediate UI updates, then confirmRead() once the server mutation succeeds to sync the optimistic state.

## Resources

- [npm package](https://www.npmjs.com/package/convex-unread-tracking)
- [GitHub repository](https://github.com/TimpiaAI/convex-unread-tracking)
- [Live demo](https://unread-tracking-demo.vercel.app/)
- [Convex Components Directory](https://www.convex.dev/components/convex-unread-tracking)
- [Convex documentation](https://docs.convex.dev)