> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hibonsai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Event reference and payload examples for the Bonsai Search web component

<Callout color="#0A5B3B" icon="circle-alert">
  All events bubble and are composed, allowing you to listen on parent elements for convenient event delegation.
</Callout>

### Reference Table

| Event     | When it fires                                    | Payload                                                      |
| --------- | ------------------------------------------------ | ------------------------------------------------------------ |
| `search`  | After the user submits a query (Enter or button) | `{ query }`                                                  |
| `results` | When initial results are received and rendered   | `{ results }`                                                |
| `ai`      | When AI-scored results/recommendations arrive    | `{ success, recommendations, results, count, maxRelevance }` |
| `error`   | When a network or parsing error occurs           | `{ error }`                                                  |

### Examples

<Callout color="#0A5B3B" icon="circle-alert">
  Fields trimmed for brevity.
</Callout>

```json theme={null}
{ "query": "What is your return policy?" }
```

```json theme={null}
{
  "results": [
    {
      "id": "product_123",
      "name": "Product Name",
      "publicUrl": "https://example.com/products/product-name",
      "price": "$42.00"
    }
  ]
}
```

```json theme={null}
{
  "success": true,
  "count": 5,
  "maxRelevance": 0.92,
  "recommendations": [
    {
      "text": "Best for small spaces",
      "productIds": ["product_123"],
      "relevancyScore": 0.91,
      "reasoning": "Compact footprint and quiet operation"
    }
  ],
  "results": [
    { "id": "product_123", "name": "Product Name", "publicUrl": "https://example.com/products/product-name" }
  ]
}
```

```json theme={null}
{ "error": "Request timed out" }
```