---
title: setCustomAttribute
source: https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/setcustomattribute
---
## Syntax
```js
newrelic.setCustomAttribute(name: string, value: string|number|boolean|null[, persist: boolean])
```
Adds a user-defined [custom attribute](https://docs.newrelic.com/docs/data-apis/custom-data/custom-events/collect-custom-attributes/) name and value to subsequent events on the page.
## Requirements
- Browser Lite, Pro, or Pro+SPA agent (v593 or higher)
- For `persist` parameter or `null` value support, agent version 1.230.0 or higher is required.
- For `boolean` value support, agent version 1.245.0 or higher is required.
- If you're installing the browser agent via npm and building a custom agent with selected features, you must enable at least one feature when creating the `Agent` instance. For example, add the following in the`features` array:
```js
import { Metrics } from '@newrelic/browser-agent/features/metrics'
const options = {
info: { ... },
loader_config: { ... },
init: { ... },
features: [
Metrics
]
}
```
For more information, see the [NPM browser installation documentation](https://www.npmjs.com/package/@newrelic/browser-agent#new-relic-browser-agent).
## Description
Sets a custom attribute for your agent session. Once an attribute is set, the New Relic platform records it with all supported events until the page is reloaded or the attribute is manually unset.
The following Browser events are supported:
| Event name | Notes |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AjaxRequest` | |
| `BrowserInteraction` | Attributes set using the SPA [`setAttribute`](https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/setattribute/) method take precedence over attributes set by `setCustomAttribute`. |
| `BrowserPerformance` | |
| `JavaScriptError` | To view or log errors for a custom attribute via API, use the browser API [`noticeError`](https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/noticeerror/) call. |
| `Log` | Custom attributes supplied to the [`log`](https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/log/) method in the `options.customAttributes` argument take precedence over attributes set by `setCustomAttribute`. |
| `PageAction` | |
| `PageView` | Make this call before the window load event fires (when that data is transmitted) in order for the attributes to be included in the [`PageView`](https://docs.newrelic.com/docs/data-apis/understand-data/event-data/events-reported-browser-monitoring/#browser-attributes-table) event. |
| `PageViewTiming` | |
| `UserAction` | |
With the `persist` flag, the attribute can also be in stored in the browser, so that subsequent page visits of the _same_ origin **within a session** span retain it on events. Do note that this functionality may fluctuate depending on end-user browser privacy settings. If this function is called with a `value = null`, the attribute will be deleted from **both** the current page's events and the storage, _regardless_ of the `persist` flag.
> #### ⚠️ IMPORTANT
>
> Be aware that persisted attributes have precedence over `info.jsAttributes` keys of the same name! For example, a persisted attribute `someName` set on `somedomain.com/pageA` will override any `someName` that is statically set on `somedomain.com/pageB`'s info block, assuming they share the same (session) storage.
## Parameters
| Parameter | Description |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` _string_ | Required. Name of the attribute. Appears as column in the `PageView` event. It will also appear as a column in the `PageAction` event if you are using it. Avoid using [reserved NRQL words](https://docs.newrelic.com/docs/insights/new-relic-insights/adding-querying-data/inserting-custom-events-attributes-insights-javascript-api#limits) when you name the attribute/value. |
| `value` _string_ OR _integer_ OR _boolean_ OR _null_ | Required. Value of the attribute. Appears as the value in the named attribute column in the `PageView` event. It will appear as a column in the `PageAction` event if you are using it. Custom attribute values cannot be complex objects, only simple types such as Strings, Integers and Booleans. Passing a `null` value unsets any existing attribute of the same name. Avoid using [reserved NRQL words](https://docs.newrelic.com/docs/insights/new-relic-insights/adding-querying-data/inserting-custom-events-attributes-insights-javascript-api#limits) when you name the attribute/value. |
| `persist` _boolean_ | Optional. If set to `true`, the name-value pair will also be set into the browser's storage API. Then on the following instrumented pages that load within the same session, the pair will be re-applied as a custom attribute. Defaults to `false`. |
## Examples
### Get JavaScript/jQuery for HTML elements [#jquery-example]
This example uses JavaScript/jQuery to get the values of the following HTML elements on a Drupal-generated page:
- ``
- `
Using NRQL
`
New Relic reports them as custom attributes. This is useful to query `PageView` and `PageAction` events.
```js
var node_id = jQuery("link[rel='shortlink']").attr("href");
var node_title = jQuery('h1').text();
if (typeof newrelic == 'object') {
newrelic.setCustomAttribute('nodeId', node_id);
newrelic.setCustomAttribute('title', node_title);
}
```