# Job brief (/ui/job-brief-card)

## What it shows [#what-it-shows]

A versioned brief with must-haves, nice-to-haves and red flags.

## Props [#props]

| Prop | Type | What it does |
| --- | --- | --- |
| `presentation` | `JobBriefCardPresentation` | `collapsible` (the default) for a page, `preview` for a message. |
| `title` | `ReactNode` | The brief's title, such as `jobBriefView`'s. With the status, it names the section. Defaults to "Job brief". |
| `titleLevel` | `2 \| 3 \| 4` | The title's heading level: 2 (the default), or 3 or 4 where the card sits deeper in the page's outline. Only the tags change, never the look. In `preview` the title is a heading at this level and the lists' and sections' headings sit one level below it. In `collapsible` the title is the kit CollapsibleSection's trigger, which can't hold a heading, so the lists' and sections' headings take this level themselves and the outline skips none. |
| `status` | `ReactNode` | At the title's end, such as an "Updated" badge, in the same place in both presentations, after the `version`. It keeps its width: on a narrow screen the title wraps rather than the status. It names the section with the title ("… Updated"), so briefs stay apart in a screen reader's list of regions. In `collapsible` it sits inside the trigger button, so pass phrasing content (a Badge rendered `as="span"`). |
| `version` | `JobBriefVersion` | Which version of the brief this is, drawn at the title's end before any `status`, as the kit StatusBadge: `jobBriefVersionLabel`'s wording ("v3 · Current" or "v2 · Earlier", or the version's own `label`), in the success tone on the version in force now and the neutral tone on an earlier one, then any `secondaryLabel` in a second, neutral badge. Like the status, it names the section with the title ("… v3 · Current"), so each version stays apart from the others. |
| `description` | `ReactNode` | What the role is, in a sentence or two. Clamped to two lines in a closed preview. |
| `facts` | `readonly JobBriefFact[]` | Headline facts after the description, such as location, salary and on-target earnings. |
| `mustHaves` | `readonly string[]` |   |
| `niceToHaves` | `readonly string[]` |   |
| `redFlags` | `readonly string[]` |   |
| `rules` | `readonly JobBriefRuleKind[]` | Which lists show, in order. Defaults to all three. Whether a page shows its red flags is the host's call: leave `redFlags` out of `rules` where they mustn't be seen. |
| `onRulesChange` | `(kind: JobBriefRuleKind, items: string[]) => void \| PromiseLike<unknown>` | Given, the lists are editable in place: each add, edit or remove hands the whole new list to the host, with which list it is. The lists stay controlled: they show the host's arrays. If the callback returns a promise, the list shows what it sent, marked busy, until the promise settles, then the host's arrays again, so a save that fails reverts and the host says why. Resolve once the arrays reflect the save. |
| `sections` | `readonly JobBriefSection[]` | Titled parts after the lists, in order, such as role details, buyers, interview steps and the company. |
| `footer` | `ReactNode` | Last, such as example candidates or an action. In `collapsible` it folds with the body; in `preview` it shows in both states, under the toggle. |
| `processing` | `boolean` | The brief is still being read from a document. With nothing to show and nothing to edit yet, an in-progress blank slate stands in for the body; otherwise a notice sits above it, so an editable brief keeps its lists and add fields however long the reading takes. |
| `loading` | `boolean` | Skeleton rows in place of a body that has nothing to show yet. |
| `open` | `boolean` | Whether the body is open: the collapsible's body, or the preview's full brief. |
| `defaultOpen` | `boolean` | Whether the body starts open when `open` is left to the card. Defaults to false. |
| `onOpenChange` | `(open: boolean) => void` |   |
| `previewCount` | `number` | In a closed preview, how many facts and how many entries of the first shown list with any show. Defaults to 3; 0 leaves the title, the description and the toggle. |
| `empty` | `CandidateEmptyCopy` | The blank slate's wording when there is nothing to show and nothing to edit. Defaults to "No brief yet". |
| `ruleLabels` | `Partial<JobBriefRuleLabels>` | The lists' names and what one entry of each is called in their controls ("Add must-have…", "Remove must-have"), such as `jobBriefView`'s. Defaults to `jobBriefLabels`' wording. |
| `labels` | `Partial<JobBriefCardLabels>` |   |

## Data it needs [#data-it-needs]

On the Kith data layer, a brief is read from a role and each edit is saved as a new version. With your own backend, pass the same values and callbacks.

It shows [`Job`](/api/reference/objects/job) from the [Kith ATS API](/api).

## Copy to your agent [#copy-to-your-agent]

```text title="Copy to your agent"
Install RecruiterOS/recruit-ui and build a job brief page with editable must-haves and a version badge.
```