---
title: View
description: Register and build one addressable Backlit screen.
---

A view is the root of one screen. Register it on a resource with a unique name.
Its resolver runs for each request and returns one content block, several content
blocks, a redirect, or an expected error.

The SDK wraps normal content in a successful protocol response. The resolver
does not create a success response.

## API

```ts
resource.view(name, resolver)
resource.view(name, params, resolver)
resource.view(name, atoms, resolver)
resource.view(name, params, atoms, resolver)
```

The resolver receives the request context and a `ViewBuilder`.

| Method           | Input    | Result                                |
| ---------------- | -------- | ------------------------------------- |
| `setTitle`       | `string` | Sets the screen title.                |
| `setDescription` | `string` | Sets supporting text under the title. |

The builder also provides `view.state.filters` when the view registers a filter bar.

## Register a view

Calling `resource.view` registers the view and returns its definition. A view
name must be unique in its resource.

<BacklitExample path="views/register" view="list" />

## Basic content

Return one block from the resolver. The SDK puts it in the view content slot.

<BacklitExample path="views/basic" view="list" />

## Multiple content blocks

Return an array to place several blocks in order.

<BacklitExample path="views/multiple_content" view="list" />

## Title

Use the view builder to set the screen title.

<BacklitExample path="views/title" view="list" />

## Description

Add a description when the title does not give sufficient context.

<BacklitExample path="views/description" view="list" />

## Async resolver

The resolver can be async. Backlit waits for it before it builds the response.

<BacklitExample path="views/async_resolver" view="list" />

## Parameters

Declare parameters in their address order. Read their typed names from
`ctx.paramValues`. The protocol node contains the argument values, not the
parameter names.

<BacklitExample path="views/params" view="detail" args={['42']} />

## Complete address

Call `definition.getAddress` with arguments in declaration order. It returns the
resource, view, string arguments, and a complete string key. A missing argument
causes an error.

<BacklitExample path="views/address" view="address" />

## Redirect

Return `ctx.redirectTo` when another view must handle the request. Pass the target
view definition. A target with parameters also requires its arguments in
declaration order. Numbers are converted to strings.

<BacklitExample path="views/redirect" expectedStatus={302} view="legacy" />

## Expected error

Return `ctx.error` for an expected request failure. Pass an HTTP error status
and a stable error code.

<BacklitExample path="views/error" expectedStatus={403} view="private" />

## Filters

Register a filter bar in the state object. Place `view.state.filters` in a
panel or section. Read its values with `ctx.parse(view).filters`.

<BacklitExample path="views/filters" view="list" />

See [Filters](/reference/filters) for all filter types and binding rules.

## Zones

Return a zone in the view content when that part of the screen must refresh on
its own.

<BacklitExample path="views/zones" view="overview" />

See [Zone](/reference/views/zone) for zone rules and combinations.

## All options

This example uses parameters, filters, a title, a description, a section, and a
zone in one view.

<BacklitExample path="views/all_options" view="detail" args={['42']} />

## Breadcrumb

`view.setBreadcrumb(record, { ancestors, fields? })` sets the header path.
Ancestors are visit targets with fixed arguments and text or icons. Optional
fields display the current record. Without fields, the header uses the view
title. Breadcrumb fields always use the display role.

<BacklitExample path="views/breadcrumb" view="detail" args={['42']} />

The view definition also exposes `resource`, `name`, `params`, `atoms`,
`getAddress`, and agent options. Use [Agent tools](/reference/agents) to opt in.
The app calls `resolve` or `resolveZone` after middleware and address checks.