---
title: "Tutorial: Build a real-time comment thread"
slug: tutorial-real-time-comments
section: guides
order: 42
level: intermediate
description: "Build a comment thread that streams new posts to every reader the moment they're written — no polling, no manual refresh. Combines @action for the post handler, dj-form-pending for the submit UX, a keyed list for rendering, and database notifications for the live broadcast."
---
# Tutorial: Build a real-time comment thread
By the end of this tutorial you'll have a comment thread that:
- Lets logged-in users **post a comment** through a single form, with
full pending/error/success UX wired through `@action` and
`dj-form-pending`.
- **Renders the existing comments** as a keyed list (`dj-key`), so
the list grows by patching in the new row rather than re-rendering
the others.
- **Streams new comments to every connected reader** within a few
hundred milliseconds of any user posting one — using PostgreSQL
`LISTEN` / `NOTIFY` (no polling, no `setInterval`).
It's the smallest realistic example of djust's "one stack, one truth"
pitch: the same Python view that handles the form submission also
broadcasts to other connected users, with no separate API or job
queue.
| You'll learn | Documented in |
|---|---|
| Server actions for form submissions | [Server Actions](server-actions.md) |
| Pending UX during submit | [Loading States](loading-states.md) |
| Rendering keyed lists | [Keyed lists (`dj-key`)](keyed-lists-performance.md) |
| Live cross-user broadcasts | [Database Notifications](database-notifications.md) |
> **Prerequisites:** The [quickstart](../getting-started/first-liveview.md), a working
> Django project with djust, a configured database (PostgreSQL for the
> live-update step), and a Django user model. Familiarity with
> [`@event_handler`](server-actions.md) helps but isn't required.
---
## What you're building
```
Comments on this post (3)
─────────────────────────
@alice · 2 min ago
This is the third comment.
@bob · 5 min ago
Glad someone built this in djust.
@carla · 10 min ago
First!
Add a comment
[ Type here… ]
[ Post ] ← flips to "Posting…" while in flight
```
When any user submits a comment, it appears in their own thread
*and* in every other open browser viewing the same thread, within
roughly the time it takes the database to publish a `NOTIFY`.
---
## Step 1 — The model
Standard Django:
```python
# myapp/models.py
from django.conf import settings
from django.db import models
class Post(models.Model):
title = models.CharField(max_length=200)
class Comment(models.Model):
post = models.ForeignKey(
Post, on_delete=models.CASCADE, related_name="comments"
)
author = models.ForeignKey(
settings.AUTH_USER_MODEL, on_delete=models.CASCADE
)
body = models.TextField()
created_at = models.DateTimeField(auto_now_add=True)
class Meta:
ordering = ["-created_at"]
```
Run `python manage.py makemigrations && migrate` and create a
single `Post` row for the demo.
---
## Step 2 — The LiveView, with the post action
Create the LiveView. We track the list of comments as state and
expose a single `@action` for posting:
```python
# myapp/views.py
from djust import LiveView, action, state
from .models import Comment, Post
class CommentThreadView(LiveView):
template_name = "comment_thread.html"
login_required = True # anonymous visitors go to settings.LOGIN_URL
post_id = state(0)
comments = state(default_factory=list)
def mount(self, request, *, post_id: int, **kwargs):
self.post_id = post_id
self.comments = self._fetch_comments()
def _fetch_comments(self):
qs = (
Comment.objects
.filter(post_id=self.post_id)
.select_related("author")
.order_by("-created_at")[:50]
)
return [
{
"id": c.id,
"author": c.author.username,
"body": c.body,
"created_at": c.created_at.isoformat(),
}
for c in qs
]
@action
def post_comment(self, body: str = "", **kwargs):
body = body.strip()
if not body:
raise ValueError("Comment cannot be empty.")
Comment.objects.create(
post_id=self.post_id,
author=self.request.user,
body=body,
)
# Re-fetch so we render the freshly-saved row alongside any
# comments that arrived from other readers in the meantime.
self.comments = self._fetch_comments()
return {"posted": True}
```
`@action` does three things compared to a bare `@event_handler`:
1. Tracks `pending / error / result` state across the handler's
lifetime.
2. Auto-injects that state into the template under the action's name
— so the template can read `post_comment.error` and
`post_comment.result` without any extra wiring. (The template
renders after the handler returns, so in-flight UX comes from
`dj-form-pending`, not from `.pending`.)
3. Lets you pair with `dj-form-pending` for declarative in-flight
form UX (see Step 3).
---
## Step 3 — The template
```html
Comments on this post ({{ comments|length }})
```
What's doing what:
| Element | Behavior |
|---|---|
| `dj-root` on the outer `` | Marks the reactive region. djust stamps `dj-view` onto it when it renders the page, and the client connects to that element. Without it the page renders but never connects: the form does a plain browser submit and no comment ever streams in. |
| `{% for %}` with `dj-key="{{ comment.id }}"` | Keyed diffing: when `self.comments` grows by one, only that one `` is inserted into the DOM. The other rows are matched by key and left alone. |
| `
{{ comment.body }}