---
name: "X-Up-Target"
area: "API"
kind: "HTTP header"
parent: "up.protocol module"
url: "https://unpoly.com/api/X-Up-Target"
---
<nav aria-label="Unpoly docs">[All docs](https://unpoly.com/index.md) · [up.protocol module](https://unpoly.com/api/up.protocol.md)</nav>

# X-Up-Target

The `X-Up-Target` request and response headers allow the server to [read](#request) or [change](#response) the [target selector](https://unpoly.com/learn/targeting-fragments.md) for a fragment update.

Server-side code is free to [optimize its response](https://unpoly.com/learn/optimizing-responses.md) by only rendering HTML that matches the selector. For example, you might prefer to not render an expensive sidebar if the sidebar is not targeted.

> #### Note
>
> Unpoly will often [update a different selector for an error response](https://unpoly.com/learn/error-responses.md#fail-options). The target selector for error responses is sent as a separate request header ([`X-Up-Fail-Target`](https://unpoly.com/api/X-Up-Fail-Target.md)).

## Detecting the targeted fragment on the server {#request}

When the user updates a fragment `.menu`, Unpoly automatically includes the following request header:

```http
X-Up-Target: .menu
```

The server chooses to render only the HTML for the updating fragment. It responds with the following HTTP:

```http
Vary: X-Up-Target

<div class="menu">...</div>
```

### Merging of request targets {#merging}

When two [caching](https://unpoly.com/learn/caching.md) requests are sent to the same URL within the same [microtask](https://developer.mozilla.org/en-US/docs/Web/API/HTML_DOM_API/Microtask_guide), only a single request is sent. The request will contain both targets in its `X-Up-Target` header.

For example, these two render passes render different selectors from `/path`:

```js
up.render('.foo', { url: '/path', cache: true })
up.render('.bar', { url: '/path', cache: true })
```

Unpoly will send a single request with both targets:

```http
GET /path HTTP/1.1
X-Up-Target: .foo, .bar
```

### Optional targets are omitted {#optional-targets}

An optional selector part ([`:maybe`](https://unpoly.com/api/maybe.md) suffix) will be omitted from the `X-Up-Target` header unless it matches in the current page.

Required selector parts are always included in the `X-Up-Target` header.

> #### Note
>
> Request headers that influenced a response should be listed in a [`Vary`](https://unpoly.com/api/Vary.md) response header. This tells Unpoly to [partition its cache](https://unpoly.com/learn/optimizing-responses.md#vary) for that URL so that each request header value gets separate cache entries.

## Changing the render target from the server {#response}

The server may change the render target context by including a CSS selector as an `X-Up-Target` header in its response.

```http
Content-Type: text/html
X-Up-Target: .selector-from-server

<div class="selector-from-server">
  ...
</div>
```

The frontend will use the `X-Up-Target` selector for both successful (HTTP status `200 OK`) and error (status `4xx` or `5xx`) responses. There is no `X-Up-Fail-Target` header in the response.

### Rendering nothing {#rendering-nothing}

The server may send an `X-Up-Target: :none` response header with an empty body to skip the current render pass.

Also see [rendering nothing](https://unpoly.com/learn/conditional-requests.md#rendering-nothing).