# Buddy — Detent

> Give your assistant a presence without an orb or a glow. Its eyes follow the pointer, look down at what you type, scan while it thinks, smile when it is done and droop when it is idle.

Canonical: https://detentui.com/components/buddy
Last updated: 2026-11-19

## About

Give your assistant a presence without an orb or a glow. Its eyes follow the pointer, look down at what you type, scan while it thinks, smile when it is done and droop when it is idle.

## When to use

- Use it for: A face for an AI assistant: avatar, launcher or a thinking state.
- Don't use it for: People’s avatars or decorative mascots with no state to show.

## Placement

Anywhere an assistant needs a face: 20 to 32 in a composer or list, 44 as a launcher, up to 96 in an empty state.

## For agents

Prompt to give a coding agent: "Add Detent's Buddy to this project. Fetch https://detentui.com/components/buddy.md and follow its "For agents" steps."

1. Check package.json: Detent needs React 19 and Tailwind CSS v4. If either is missing or older, stop and tell the user.
2. If the project root has no components.json, run `npx shadcn@latest init --defaults --yes` there.
3. Install it from the project root: `npx shadcn@latest add https://detentui.com/r/buddy`
4. Make sure the root layout (in Next.js, app/layout.tsx) wraps its children once in `<MotionConfig reducedMotion="user">` from motion/react. Add it only if it is not there.
5. Import `Buddy` from `@/components/detent/components/buddy/Buddy` and render it where the user asked, sized and placed as the Placement section says. Start from the Example below, keep its layout, and swap in the project's real data.
6. If the project has no real data for it yet, put clearly marked placeholders in one content file. Never invent customer quotes, names or numbers and present them as real.
7. Detent pieces are client components. If you pass them functions (format, onChange, render props), do it from a client component; a server page can only pass plain data, so load the data on the server and hand it to a small client wrapper.
8. Use the Detent theme tokens (like bg-surface, text-ink, text-ink-3) for anything you draw around it, and className where the piece takes one. Don't rewrite its motion or internals.
9. Run the project's typecheck (for example `npx tsc --noEmit`; on a fresh Next.js project run `npx next typegen` first, or it can't find types like LayoutProps). If you can run the app, open the page at a desktop and a phone width and check it renders with no console errors.
10. If AGENTS.md or CLAUDE.md has no Detent section yet, add the block from https://detentui.com/agents.md so later tasks pick the right pieces.
11. Tell the user what you added, where, and anything they still need to fill in.

## Details

- Five moods: `idle`, `listening`, `thinking`, `happy` and `sleepy`. Set `mood` from your app state.
- Idle eyes follow the pointer within reach; they blink now and then at random.
- Three tones, `ink`, `paper` and `blue`, and any `size` from 16 up. Use it as an avatar, a launcher or a loading mark.
- Pass `label` to announce it to screen readers; otherwise it is decorative. Reduced motion keeps the eyes still.

## Install

Free, MIT licensed.

```bash
npx shadcn add https://detentui.com/r/buddy
```

Needs React 19 and Tailwind CSS v4. The source lands in components/detent; import it from `@/components/detent/components/buddy/Buddy`.

## Looks like

![Buddy](https://detentui.com/components/buddy/opengraph-image)

This is the example below, rendered. The live, interactive version is at https://detentui.com/components/buddy.

## Example

A working example that typechecks against the installed piece. Keep its layout as a starting point and swap the sample data for the project's real data. Outer wrappers like `size-full` or a dark background come from the demo stage: give the parent a real size, or drop them.

```tsx
'use client'

import { useEffect, useRef, useState } from 'react'
import { Buddy } from '@/components/detent/components/buddy/Buddy'
import type { BuddyMood } from '@/components/detent/components/buddy/Buddy'
import { IRIS } from '@/components/detent/lib/iris'

const MOODS: BuddyMood[] = ['idle', 'listening', 'thinking', 'happy', 'sleepy']
export function BuddyExample() {
  const [mood, setMood] = useState<BuddyMood>('idle')
  const [text, setText] = useState('')
  const timer = useRef(0)
  const run = () => {
    window.clearTimeout(timer.current)
    setText('')
    setMood('thinking')
    timer.current = window.setTimeout(() => {
      setMood('happy')
      timer.current = window.setTimeout(() => setMood('idle'), 1600)
    }, 1400)
  }
  useEffect(() => () => window.clearTimeout(timer.current), [])
  const shown: BuddyMood = mood === 'idle' && text ? 'listening' : mood
  return (
    <div style={IRIS} className="flex size-full flex-col items-center justify-center gap-6 p-4">
      <Buddy size={88} mood={shown} label={`Buddy, ${shown}`} />
      <form
        onSubmit={(e) => {
          e.preventDefault()
          if (text.trim()) run()
        }}
        className="flex h-11 w-[300px] max-w-full items-center gap-2 rounded-full bg-[var(--i-tray)] pl-4 pr-1.5 shadow-[inset_0_0_0_0.5px_var(--i-edge)]"
      >
        <input value={text} onChange={(e) => setText(e.target.value)} placeholder="Type, then press Enter" aria-label="Message" className="min-w-0 flex-1 bg-transparent text-[13px] text-[var(--i-t1)] outline-none placeholder:text-[var(--i-t3)] pointer-coarse:text-[16px]" />
      </form>
      <div role="radiogroup" aria-label="Mood" className="flex flex-wrap justify-center gap-1">
        {MOODS.map((m) => (
          <button key={m} type="button" role="radio" aria-checked={mood === m} onClick={() => setMood(m)} className={`h-7 rounded-full px-2.5 text-[12px] capitalize transition-[transform,background-color,color] duration-150 active:scale-[.97] ${mood === m ? 'bg-[var(--i-ink)] text-[var(--i-ink-on)]' : 'text-[var(--i-t2)] hover:bg-[var(--i-hover)]'}`}>
            {m}
          </button>
        ))}
      </div>
      <div className="flex items-center gap-3">
        <Buddy size={20} tone="ink" />
        <Buddy size={28} tone="paper" />
        <Buddy size={36} tone="blue" />
      </div>
    </div>
  )
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `number` | `40` | Width and height in pixels. |
| `mood` | `BuddyMood` | `'idle'` | idle follows the pointer, listening looks down, thinking scans, happy smiles, sleepy droops. |
| `tone` | `keyof typeof TONES` | `'ink'` | ink, paper or blue. |
| `label` | `string` |  | Text for screen readers. Leave it out when Buddy is decorative. |

## Motion and accessibility

- Wrap your root layout once in `<MotionConfig reducedMotion="user">` from motion/react; every Detent piece then respects reduced motion.
- Style it through the Detent theme tokens and `className`, not by editing internals first.

Every Detent piece, with when to use each: https://detentui.com/llms.txt · Agent rules to paste into AGENTS.md: https://detentui.com/agents.md

## Related
- [All components](https://detentui.com/components)
- [Pro](https://detentui.com/pro)
