# Invite Row

An email field and a role picker for inviting one person, with a button to remove the row.

- Category: Forms
- Page: https://wunderui.com/components/invite-row
- Tier: Free

## Install

```bash
npx wunderui-cli add invite-row
```

## Import

```tsx
import { InviteRow, InviteRowProps } from "@/components/blocks/auth"
```

## Minimal usage

Then use it:

```tsx
import { useState } from "react"
import { InviteRow } from "@wunderui/react"

export function Invite() {
  const [email, setEmail] = useState("daniel.okafor@wunderui.com")
  const [role, setRole] = useState("Editor")

  return <InviteRow email={email} role={role} onEmailChange={setEmail} onRoleChange={setRole} />
}
```

Expected result: You see an email field and a role select showing Editor, side by side on a wide screen. Typing and picking change them.

## Usage

```tsx
import { useState } from "react"
import { InviteRow } from "@wunderui/react"

export function Example({ onRemove }: { onRemove: () => void }) {
  const [email, setEmail] = useState("daniel.okafor@wunderui.com")
  const [role, setRole] = useState("Editor")

  return (
    <InviteRow
      email={email}
      role={role}
      onEmailChange={setEmail}
      onRoleChange={setRole}
      onRemove={onRemove}
    />
  )
}
```

## When to use

### Use Invite Row for

- A list of people to invite, one email and one role per row
- A row that can be removed from the list
- A role chosen from a short list

### Use something else

- [Input Group](https://wunderui.com/components/input-group) for one shareable link with a copy button
- [Field](https://wunderui.com/components/field) for a single labelled input with its own error message
- [Select](https://wunderui.com/components/select) for a role or option picker on its own
- [Settings Row](https://wunderui.com/components/settings-row) for a setting with a title, a description and a control

## Keyboard

A row has up to three tab stops, in this order: the email field, the role select, the remove button. The remove button exists only with a remove handler.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus between the email field, the role select and the remove button, then on to the next row. |
| `Enter` or `Space` or `ArrowDown` | On the role select: opens the list. |
| `ArrowUp` or `ArrowDown` | In the open list: moves to the previous or next role. |
| `Enter` | In the open list: picks the highlighted role, closes the list and calls `onRoleChange`. |
| `Esc` | Closes the open list without a change and returns focus to the select. |
| `Enter` or `Space` | On the remove button: presses it and calls `onRemove`. |

## Behavior

What an invite row does with state, content, the DOM and motion.

- **Controlled:** The row keeps no value of its own. Typing and picking call your change handlers, and the row shows what you pass back; without a handler the field stays as it is.
- **Layout:** From 640 px the email, role select and 36 px remove button sit in one row with a 12 px gap. Below that, or when stacked, the email is on top and the select and button under it.
- **States:** Each control keeps the states of its own component. The row itself has no loading, error or disabled state, so write error messages yourself under the row.
- **Long text:** A long address doesn't wrap or get cut with an ellipsis: it scrolls inside the field. Role names stay on one line in the select.
- **Names for assistive technology:** The field is named Email, the select Role and the button Remove, the same on every row. Screen reader users can't tell rows apart by those names, so say which row changed in a status line.
- **Motion and reduced motion:** The role list opens with a short fade and scale and leaves faster, and control colours change quickly. With reduced motion the list appears without a transition.

## Anatomy

- `InviteRow`: A flex container with a 12 px gap between the email and the role, with no border or fill. From the small breakpoint up they sit in one row; below that, or when stacked, one over the other.
- `Email field`: An Input of type email, named Email, that takes the rest of the row. It shows the placeholder info@wunderui.com while empty.
- `Role select`: A NativeSelect named Role, at least 9 rem wide, with the roles you pass. The list opens below the field.
- `Remove button`: A plain icon button with a 16 px X, named Remove. It is drawn only when you pass a remove handler.

## Best practices

### When to use

- Use Invite Row for each person in a team invite list, one row per invitee. For one shareable link, use Invite Link Row.

### Do

- Keep it controlled: pass the email and role with their change handlers. Without the handlers the fields don't change when someone types or picks.
- Pass your own roles when the defaults (Admin, Editor, Viewer) don't match the product, and make sure the current role is one of them.
- Use the stacked layout in a narrow container. The row switches layout with the screen width, not its container's, so a narrow dialog on a wide screen stays inline.
- Validate in your handler and write the message under the row, like Enter a valid email address. The row has no error state, so name the address when checking several rows.
- After a row is removed, move focus to the list and say which address went in a status line. Every remove button is named just Remove.

### Don't

- Don't pass a remove handler to a row you must keep. The remove button is drawn only when the handler exists.
- Don't use real addresses in docs or tests. The addresses in the demos belong to made-up people.

## API reference

### InviteRow

| Prop | Type | Default | Description |
|---|---|---|---|
| email* | string |  | The value of the email field. Required, and controlled: the field shows exactly this text. |
| role* | string |  | The selected role. It should be one of `roles`. Required, and controlled. |
| className | string |  | Added to the row. Use it for the width. |
| onEmailChange | (email: string) => void |  | Called with the new text each time the email changes. Without it the field does not change. |
| onRemove | () => void |  | Adds the remove button and is called when it is pressed. Take the row out of your list in the handler. |
| onRoleChange | (role: string) => void |  | Called with the picked role. Without it the select does not change. |
| roles | string[] | ["Admin", "Editor", "Viewer"] | The roles in the select, as strings that are also the labels. Defaults to Admin, Editor and Viewer. |
| stacked | boolean |  | Puts the email over the role and the button at every width. Without it the row stacks only below 640 px. |

## Examples

### Layout: inline and stacked

```tsx
import { useState } from "react"
import { InviteRow } from "@wunderui/react"

export function Example({ onRemove }: { onRemove: () => void }) {
  const [email, setEmail] = useState("daniel.okafor@wunderui.com")
  const [role, setRole] = useState("Editor")

  return (
    <InviteRow
      email={email}
      role={role}
      onEmailChange={setEmail}
      onRoleChange={setRole}
      onRemove={onRemove}
    />
  )
}
```

### Remove: with and without the button

```tsx
import { useState } from "react"
import { InviteRow } from "@wunderui/react"

export function Example({ onRemove }: { onRemove: () => void }) {
  const [email, setEmail] = useState("daniel.okafor@wunderui.com")
  const [role, setRole] = useState("Editor")

  return (
    <InviteRow
      email={email}
      role={role}
      onEmailChange={setEmail}
      onRoleChange={setRole}
      onRemove={onRemove}
    />
  )
}
```

### Roles: default and your own

```tsx
import { useState } from "react"
import { InviteRow } from "@wunderui/react"

export function Example({ onRemove }: { onRemove: () => void }) {
  const [email, setEmail] = useState("daniel.okafor@wunderui.com")
  const [role, setRole] = useState("Editor")

  return (
    <InviteRow
      email={email}
      role={role}
      onEmailChange={setEmail}
      onRoleChange={setRole}
      onRemove={onRemove}
    />
  )
}
```

### Content: filled, empty, long and invalid

```tsx
import { useState } from "react"
import { InviteRow } from "@wunderui/react"

export function Example({ onRemove }: { onRemove: () => void }) {
  const [email, setEmail] = useState("daniel.okafor@wunderui.com")
  const [role, setRole] = useState("Editor")

  return (
    <InviteRow
      email={email}
      role={role}
      onEmailChange={setEmail}
      onRoleChange={setRole}
      onRemove={onRemove}
    />
  )
}
```

## In context

### Team invite dialog: rows with roles and a seat limit

Edit addresses and roles, remove a row or add one while seats are left. Send checks every address and names the wrong one, Cancel puts the rows back, and nothing is actually sent.

```tsx
import { useRef, useState } from "react"
import { Plus } from "lucide-react"
import {
  Button,
  Dialog,
  DialogBody,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  InviteRow,
} from "@wunderui/react"

const ROLES = ["Admin", "Member", "Viewer"]
const SEATS = 3
const VALID = /^[^\s@]+@[^\s@]+\.[^\s@]+$/

type Row = { id: number; email: string; role: string }

export function InviteDialog({ open, onOpenChange, onSend }: { open: boolean; onOpenChange: (open: boolean) => void; onSend: (rows: Row[]) => void }) {
  const [rows, setRows] = useState<Row[]>([
    { id: 1, email: "priya.raman@wunderui.com", role: "Admin" },
    { id: 2, email: "daniel.okafor@wunderui.com", role: "Member" },
    { id: 3, email: "", role: "Member" },
  ])
  const [next, setNext] = useState(4)
  const [error, setError] = useState("")
  const list = useRef<HTMLDivElement>(null)

  const filled = rows.filter((row) => row.email.trim())
  const update = (id: number, patch: Partial<Row>) => {
    setError("")
    setRows((items) => items.map((row) => (row.id === id ? { ...row, ...patch } : row)))
  }

  function remove(id: number) {
    setRows((items) => items.filter((row) => row.id !== id))
    list.current?.focus() // the focused remove button is gone: keep the keyboard in the list
  }

  function add() {
    setRows((items) => [...items, { id: next, email: "", role: "Member" }])
    setNext(next + 1)
  }

  function send() {
    const wrong = filled.findIndex((row) => !VALID.test(row.email.trim()))
    if (wrong >= 0) {
      setError("Check the address of " + filled[wrong].email.trim() + ". Enter a valid email address.")
      return
    }
    onSend(filled)
    onOpenChange(false)
  }

  return (
    <Dialog open={open} onOpenChange={onOpenChange}>
      <DialogContent size="md">
        <DialogHeader>
          <DialogTitle>Invite your team</DialogTitle>
          <DialogDescription>You have {SEATS} seats left. Each person gets an email with a link to join WunderUI.</DialogDescription>
        </DialogHeader>
        <DialogBody>
          <div ref={list} tabIndex={-1} className="flex flex-col gap-3 outline-none">
            {rows.map((row) => (
              <InviteRow
                key={row.id}
                email={row.email}
                role={row.role}
                roles={ROLES}
                onEmailChange={(email) => update(row.id, { email })}
                onRoleChange={(role) => update(row.id, { role })}
                onRemove={() => remove(row.id)}
              />
            ))}
            <p role="alert" className="min-h-4 text-xs text-text-error">
              {error}
            </p>
            <Button size="sm" variant="plain" className="self-start" disabled={rows.length >= SEATS} onClick={add}>
              <Plus className="size-4" strokeWidth={1.5} />
              Add another
            </Button>
          </div>
        </DialogBody>
        <DialogFooter>
          <Button variant="plain" onClick={() => onOpenChange(false)}>
            Cancel
          </Button>
          <Button variant="gradient" disabled={filled.length === 0} onClick={send}>
            {"Send " + filled.length + (filled.length === 1 ? " invite" : " invites")}
          </Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}
```

### Bulk invite: paste several addresses

Paste addresses separated by commas or spaces and press Add. Valid new addresses become rows with the Member role, and the others are counted under the field, with a sample to try.

```tsx
import { useRef, useState } from "react"
import { Button, Input, InviteRow } from "@wunderui/react"

const ROLES = ["Admin", "Member", "Viewer"]
const VALID = /^[^\s@]+@[^\s@]+\.[^\s@]+$/

type Row = { id: number; email: string; role: string }

export function BulkInvite() {
  const [rows, setRows] = useState<Row[]>([
    { id: 1, email: "maya.kessler@wunderui.com", role: "Member" },
  ])
  const [text, setText] = useState("")
  const [message, setMessage] = useState("")
  const next = useRef(2)
  const section = useRef<HTMLElement>(null)

  function add() {
    const found = text.split(/[\s,;]+/).filter(Boolean)
    const good = found.filter((email) => VALID.test(email) && !rows.some((row) => row.email === email))
    const skipped = found.length - good.length
    setRows((list) => [...list, ...good.map((email) => ({ id: next.current++, email, role: "Member" }))])
    setText("")
    setMessage((good.length === 1 ? "Added 1 address." : "Added " + good.length + " addresses.") + (skipped ? " Skipped " + skipped + ": not valid or already listed." : ""))
    section.current?.querySelector("input")?.focus() // the Add button is disabled again: keep the keyboard in the field
  }

  return (
    <section ref={section} aria-label="Invite by email" className="flex flex-col gap-3">
      <div className="flex gap-2">
        <Input value={text} onChange={(event) => setText(event.target.value)} placeholder="Paste addresses, separated by commas or spaces" aria-label="Addresses" />
        <Button variant="plain" disabled={!text.trim()} onClick={add}>
          Add
        </Button>
      </div>
      <p role="status" className="min-h-4 text-xs text-text-secondary">
        {message}
      </p>
      {rows.map((row) => (
        <InviteRow
          key={row.id}
          email={row.email}
          role={row.role}
          roles={ROLES}
          onEmailChange={(email) => setRows((list) => list.map((item) => (item.id === row.id ? { ...item, email } : item)))}
          onRoleChange={(role) => setRows((list) => list.map((item) => (item.id === row.id ? { ...item, role } : item)))}
          onRemove={() => setRows((list) => list.filter((item) => item.id !== row.id))}
        />
      ))}
    </section>
  )
}
```

## For AI agents

`get_component("invite-row")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
