# Choices

Turn what people type into choices from your options, for filters, search, and command palettes.

:hero-figure{name="choices"}

```ts [server/utils/forecast-choices.ts] fragment
import { defineChoices, toOptions } from 'vite-hub/choices'
import { typesafe } from 'vite-hub/gateways'

// Bridge in: your data becomes options
export const forecast = defineChoices({
  gateway: typesafe(), // reads TYPESAFE_API_KEY
  groups: {
    supplier: {
      label: 'Supplier',
      options: toOptions(suppliers, {
        value: s => s.id,
        label: s => s.name,
      }),
    },
  },
})
```

```ts [server/api/choices.post.ts]
import { defineEventHandler, HTTPError, readValidatedBody } from 'h3'
import * as v from 'valibot'
import { forecast } from '../utils/forecast-choices'

// The route is yours. Add auth and limits here.
export default defineEventHandler(async (event) => {
  const { text } = await readValidatedBody(event, v.parser(v.object({ text: v.string() })))
  const [error, selection] = await forecast.resolve(text)
  if (error) throw new HTTPError({ status: 422, message: error.message })
  return selection
})
```

```vue [FilterBar.vue]
<script setup lang="ts">
import { useChoices } from 'vite-hub/choices/vue'
import type { forecast } from '~~/server/utils/forecast-choices'

const filters = useFilters() // your state
const ai = useChoices<typeof forecast>({
  resolve: (text, { signal }) =>
    $fetch('/api/choices', { method: 'POST', body: { text }, signal }),
  // Bridge out: the selection becomes your state
  onSelect: selection => filters.setSuppliers(selection.supplier),
})
</script>

<template>
  <input v-model="ai.text.value" @keydown.enter="ai.submit()">
</template>
```

### [Declare options, get typed choices](https://vitehub.dev/docs/choices/server-api#define-choices)

`defineChoices()` types the selection from your options.

### [Include and exclude](https://vitehub.dev/docs/choices/concepts#selection)

"nord parts except vak supply" includes one supplier and excludes one.

### [The model cannot invent a value](https://vitehub.dev/docs/choices/concepts#the-model-never-invents-a-value)

Each selected value is one of your options.

### [You own the route and the state](https://vitehub.dev/docs/choices/client)

Auth, limits, and filters stay in your code. `useChoices()` connects them.

### [Try it with no API key](https://vitehub.dev/docs/choices/get-started)

The tutorial runs offline. The last step adds a real model.

### [Know the limits](https://vitehub.dev/docs/choices/limits-and-errors#limits)

100 options, 300 characters of text, and one error code per failure.

Use Choices to turn free text into a typed selection over options that the app declares. Choices has no routes, no UI, and no store. Write the two bridges: data to options, and selection to state.

Call `resolve()` only on the server, inside a route that you own. Never import the choices value in browser code. Import its type with `import type`. A decision model cannot compare numbers or invent a value, so keep numeric filters in normal controls.

Prove it with `inspect()` first, then with a test gateway that has `ask()`. Do not claim live model behavior without a key.

<!-- vitehub-docs:section-links -->
## In this section

- [Overview](https://vitehub.dev/raw/docs/choices.md) (this page)
- [Get started](https://vitehub.dev/raw/docs/choices/get-started.md)
- [Server API](https://vitehub.dev/raw/docs/choices/server-api.md)
- [Limits and errors](https://vitehub.dev/raw/docs/choices/limits-and-errors.md)
- [Client](https://vitehub.dev/raw/docs/choices/client.md)
- [Recipes](https://vitehub.dev/raw/docs/choices/recipes.md)
- [Concepts](https://vitehub.dev/raw/docs/choices/concepts.md)

Next: [DECISIONS_R0001](https://vitehub.dev/raw/docs/choices/diagnostics/decisions_r0001.md)

All pages: [llms.txt](https://vitehub.dev/llms.txt)
