diff --git a/apps/www/pages/reference/primitives/Thread.mdx b/apps/www/pages/reference/primitives/Thread.mdx
index fcb4d3d33..a2bed41ca 100644
--- a/apps/www/pages/reference/primitives/Thread.mdx
+++ b/apps/www/pages/reference/primitives/Thread.mdx
@@ -166,6 +166,68 @@ const ScrollToBottom = () => {
 };
 ```
 
+### `ThreadPrimitive.Suggestion`
+
+Shows a suggestion to the user. When the user clicks on the suggestion, the composer's value is set to the suggestion's prompt.
+
+This primitive renders a `<button>` element unless `asChild` is set.
+
+```tsx
+import { ThreadPrimitive } from "@assistant-ui/react";
+
+const Suggestion = () => {
+  return (
+    <ThreadPrimitive.Suggestion
+      prompt="I need help with product search"
+      method="replace"
+      autoSend
+    />
+  );
+};
+
+<ParametersTable
+  type="ThreadPrimitiveSuggestionProps"
+  parameters={[
+    {
+      name: "prompt",
+      type: "string",
+      description: "The suggestion's prompt.",
+    },
+    {
+      name: "method",
+      type: "'replace'",
+      description: "How does the suggestion interact with the composer's existing value.",
+    },
+    {
+      name: "autoSend",
+      type: "boolean",
+      description: "Whether to automatically send the suggestion when the user clicks on it.",
+      default: "false",
+    },
+  ]}
+/>
+```
+
+#### `useThreadSuggestion`
+
+```tsx
+import { useThreadSuggestion } from "@assistant-ui/react";
+
+const Suggestion = () => {
+  const suggestion = useThreadSuggestion({
+    prompt: "Write me a poem about the weather",
+    method: "replace",
+    autoSend: true,
+  });
+
+  return (
+    <button onClick={suggestion}>
+      Write me a poem about the weather
+    </button>
+  );
+};
+```
+
 ### If
 
 Renders children if a condition is met.