

<Preview name="ReasoningShowcaseExample" />

## Overview [#overview]

`Reasoning` displays model reasoning or thinking text behind a collapsible trigger. Consumers own the text, streaming status, and persistence.

The trigger shows active thinking with `isStreaming`, auto-opens when reasoning starts, and auto-closes after reasoning finishes.

## Usage [#usage]

```tsx
import {
  Reasoning,
  ReasoningContent,
  ReasoningTrigger,
} from "@tilt-legal/cubitt-components/chat-elements";
```

## Examples [#examples]

### Default [#default]

<Tabs items="['Preview', 'Code']">
  <Tab value="Preview">
    <Preview name="ReasoningDefaultExample" />
  </Tab>

  <Tab value="Code">
    ```tsx
    <Reasoning defaultOpen duration={4}>
      <ReasoningTrigger />
      <ReasoningContent>
        I checked the uploaded lease summary first because it contains the operative
        termination language.
      </ReasoningContent>
    </Reasoning>
    ```
  </Tab>
</Tabs>

### Streaming [#streaming]

<Tabs items="['Preview', 'Code']">
  <Tab value="Preview">
    <Preview name="ReasoningStreamingExample" />
  </Tab>

  <Tab value="Code">
    ```tsx
    <Reasoning isStreaming>
      <ReasoningTrigger />
      <ReasoningContent>
        Checking the matter sources before drafting the final response...
      </ReasoningContent>
    </Reasoning>
    ```
  </Tab>
</Tabs>

## API Reference [#api-reference]

### Reasoning [#reasoning]

Root collapsible container for reasoning text. Extends Collapsible props.

| Prop           | Type                      | Default       | Description                                                                                    |
| -------------- | ------------------------- | ------------- | ---------------------------------------------------------------------------------------------- |
| `isStreaming`  | `boolean`                 | `false`       | Marks reasoning as actively streaming. Auto-opens the disclosure when streaming starts.        |
| `open`         | `boolean`                 | -             | Controlled open state.                                                                         |
| `defaultOpen`  | `boolean`                 | `isStreaming` | Initial open state when uncontrolled. Pass `false` to opt out of auto-open.                    |
| `onOpenChange` | `(open: boolean) => void` | -             | Callback fired when the disclosure opens or closes.                                            |
| `duration`     | `number`                  | -             | Controlled thinking duration in seconds. If omitted, duration is measured from streaming time. |
| `children`     | `React.ReactNode`         | -             | Reasoning trigger and content.                                                                 |
| `className`    | `string`                  | -             | Additional CSS classes for the root collapsible.                                               |

### ReasoningTrigger [#reasoningtrigger]

Trigger for the reasoning disclosure. Extends CollapsibleTrigger props.

| Prop                 | Type                                                     | Default | Description                                                              |
| -------------------- | -------------------------------------------------------- | ------- | ------------------------------------------------------------------------ |
| `getThinkingMessage` | `(isStreaming: boolean, duration?: number) => ReactNode` | -       | Custom renderer for the default trigger label.                           |
| `children`           | `React.ReactNode`                                        | -       | Custom trigger content. Replaces the default thinking label and chevron. |
| `className`          | `string`                                                 | -       | Additional CSS classes for the trigger.                                  |

The default trigger shows a shimmer while streaming, then displays the measured thinking duration when available.

### ReasoningContent [#reasoningcontent]

Collapsible panel that renders reasoning markdown through Streamdown.

| Prop        | Type     | Default | Description                                       |
| ----------- | -------- | ------- | ------------------------------------------------- |
| `children`  | `string` | -       | Reasoning markdown text. Required.                |
| `className` | `string` | -       | Additional CSS classes for the collapsible panel. |

### useReasoning [#usereasoning]

Hook for custom reasoning subcomponents. Must be called within `Reasoning`.

| Field         | Type                      | Description                                       |
| ------------- | ------------------------- | ------------------------------------------------- |
| `isStreaming` | `boolean`                 | Whether the current reasoning block is streaming. |
| `isOpen`      | `boolean`                 | Current open state.                               |
| `setIsOpen`   | `(open: boolean) => void` | Updates the open state and calls `onOpenChange`.  |
| `duration`    | `number \| undefined`     | Current thinking duration in seconds.             |