---
title: Lookup target
description: Let a form input select a value from fetched records.
---

A lookup target connects an input to a lookup registered on a resource. The
lookup declares the fields its records return. The target names the lookup and
supplies the args for its params. An input variant holds the target and names
the two fields the control reads: `value`, the field a taken record writes into
the input, and `label`, the field the closed input shows.

Two input variants use a lookup target. `lookupVia` makes a picker with a
search. `optionsVia` makes a closed list. An enum field and a ref field accept
both.

## API

```ts
lookupVia(
  source: LookupDefinition | (() => LookupDefinition),
  args?: (FieldBuilder | string | number | boolean)[],
  options: {
    value: string
    label: string
    create?: VisitTarget
  }
): SearchInputVariant

optionsVia(
  source: LookupDefinition | (() => LookupDefinition),
  args?: (FieldBuilder | string | number | boolean)[],
  options: {
    value: string
    label: string
  }
): OptionsInputVariant
```

`value` and `label` must name fields the lookup's resolver declares. TypeScript
checks both names, and checks that the `value` field's value fits the input
field. The value is a scalar, always, because that is what a store holds.

`args` is required when the lookup declares params, and not permitted when it
declares none. The tuple has one entry for each param, in param order. A field
builder is read on the client as the value of the field with that name on the
same record as the input. A literal is sent as it is.

## Search picker

The picker searches the lookup and shows its declared fields. Taking a record
writes its `value` field to the input.

<BacklitExample path="targets/lookup/basic" view="detail" />

## Closed list with params

The lookup declares a param. The state input supplies the country field as
its arg. The client reads the country beside the state, asks the lookup when
the country has a value, and asks again when it changes. A change clears the
state.

<BacklitExample path="targets/lookup/params" view="create" />

## Create target

Pass `create` to `lookupVia` to let the picker offer to make the record it
cannot find: one complete visit target, ordinarily opening a create view in a
dialog over the form.

```ts
lookupVia(categoryPicker, {
  value: 'name',
  label: 'name',
  create: visitTo(categoryCreate, [], {
    text: 'New category',
    mode: 'drawer',
  }),
})
```

## Thunk

Pass the lookup definition as a function when resource modules refer to each
other. Backlit reads it when it creates the protocol node.

<BacklitExample path="targets/lookup/thunk" view="detail" />