---
title: "How to set and update user properties in React"
description: "Set, update, and remove Amplitude user properties in React. Use Identify operations and verify first values, counters, and event history."
canonical: "https://amplitude.com/build/react-user-properties"
---

# How to set and update user properties in React

Set, update, and remove Amplitude user properties in React. Use Identify operations and verify first values, counters, and event history.

Source: https://amplitude.com/build/react-user-properties

---

# How to set and update user properties in React

Use an Identify object to set user properties, keep a first value, increment a counter, or remove a property. Build a React example and verify the property history on subsequent events in about 20 minutes.

- React
- Vite
- Unified SDK 1.2.1
- 20 min

Chris Tam · Last updated 13 November 2026

[Product analytics](https://amplitude.com/amplitude-analytics) uses user properties to describe who performs an action. I'll update a synthetic demo user's plan and theme. These controls change analytics properties; they don't change billing or application preferences.

In this tutorial, I'll set and remove properties, preserve the first theme, and verify a counter on follow-up events. The [React analytics tutorial](https://amplitude.com/build/react-product-analytics) covers broader instrumentation; this example includes its own setup.

## What you'll build

An app that applies `plan` and `preferred_theme`, records `first_theme` once, adds to `preference_updates`, and clears the theme. Ordinary events sent afterward show how those properties change over time.

## Prerequisites

- Node.js 22.12 or later and Corepack for pnpm.
- An Amplitude test project and its ingestion API key. Open Organization settings > API Keys and select the test project.
- The project data center, US or EU. Preserve your existing consent flow when adapting the example.

No Amplitude account yet? A free account is enough for this tutorial; nothing here needs a paid plan. [Sign up for free](https://app.amplitude.com/signup) to get your project API key.

## 1. Create the standalone app

I'll use the [Browser Unified SDK package installation](https://amplitude.com/docs/get-started/install-with-package-manager) in a small Vite app. The versions below are pinned to the tested example.

Terminal

```sh
mkdir react-user-properties
cd react-user-properties
mkdir -p src tests
corepack enable
```

package.json

```json
{
  "name": "amplitude-react-user-properties",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "packageManager": "pnpm@10.33.2+sha512.a90faf6feeab71ad6c6e57f94e0fe1a12f5dcc22cd754db40ae9593eb6a3e0b6b12e3540218bb37ae083404b1f2ce6db2a4121e979829b4aff94b99f49da1cf8",
  "engines": {
    "node": ">=22.12.0",
    "pnpm": ">=10.21.0"
  },
  "scripts": {
    "dev": "vite --host 127.0.0.1",
    "build": "vite build",
    "preview": "vite preview --host 127.0.0.1",
    "test": "node --test tests/*.test.mjs"
  },
  "dependencies": {
    "@amplitude/unified": "1.2.1",
    "react": "19.3.1",
    "react-dom": "19.3.1"
  },
  "devDependencies": {
    "vite": "8.3.6"
  }
```

pnpm-workspace.yaml

```yaml
minimumReleaseAge: 10080
trustPolicy: no-downgrade
```

.gitignore

```text
node_modules/
dist/
.env
.env.local
.env.*.local
```

index.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>User properties demo</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>
```

.env.example

```text
VITE_AMPLITUDE_API_KEY=
VITE_AMPLITUDE_SERVER_ZONE=US
```

Terminal

```sh
corepack prepare pnpm@10.33.2 --activate
pnpm install
cp .env.example .env.local
```

Put the test-project key in `VITE_AMPLITUDE_API_KEY` in `.env.local`, and set `VITE_AMPLITUDE_SERVER_ZONE` to `US` or `EU`. Vite exposes `VITE_` variables in the browser bundle. The project API key is public and has the minimum scope needed to ingest data; a server secret key stays out of browser code.

In an existing application, merge the changes into its current Amplitude module and application flow. Keep authentication, consent, routes, and other instrumentation. Don't add another SDK installation or replace production files with the demo.

## 2. Build explicit Identify operations

I'll construct each update with [Identify methods](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2/reference#identify). The form accepts fixed categories, and each property appears in one operation per Identify object.

src/properties.js

```javascript
import { Identify } from '@amplitude/unified';

export function preferenceValues(input) {
  if (!['starter', 'pro'].includes(input?.plan)
    || !['light', 'dark'].includes(input?.theme)) {
    throw new Error('Choose one of the listed plans and themes.');
  }
  return { plan: input.plan, theme: input.theme };
}

export function preferenceIdentify(input) {
  const { plan, theme } = preferenceValues(input);
  return new Identify()
    .set('plan', plan)
    .set('preferred_theme', theme)
    .setOnce('first_theme', theme)
    .add('preference_updates', 1);
}

export function clearedThemeIdentify() {
  return new Identify().unset('preferred_theme');
}
```

`set` replaces a value, `setOnce` preserves an existing first value, and `add` increments a number. A missing numeric property starts at zero. `unset` removes the property. The separate object for clearing avoids conflicting operations on `preferred_theme`.

**Why.**` preference_updates` counts accepted demo updates, not successful billing transactions or unique actions across retries. An additive update isn't an idempotent transaction. Don't blindly repeat `add` after an ambiguous network result.

## 3. Identify the demo user and send a following event

I'll initialize once, assign a synthetic ID that persists in this origin, and send a normal event after each accepted Identify operation. In a real application, use the stable ID from your authenticated account instead of this demo ID.

src/analytics.js

```javascript
import * as amplitude from '@amplitude/unified';
import { preferenceIdentify, preferenceValues, clearedThemeIdentify } from './properties.js';

let ready;
let enabled = false;

export function initializeAnalytics() {
  const apiKey = import.meta.env.VITE_AMPLITUDE_API_KEY?.trim();
  if (!apiKey) return Promise.resolve({ status: 'disabled', userId: null, deviceId: null });
  if (!ready) {
    ready = amplitude.initAll(apiKey, {
      instanceName: 'build-user-properties',
      serverZone: import.meta.env.VITE_AMPLITUDE_SERVER_ZONE === 'EU' ? 'EU' : 'US',
      analytics: { autocapture: false, remoteConfig: { fetchRemoteConfig: false } },
      sessionReplay: { sampleRate: 0 },
      engagement: { skip: true },
    }).then(() => {
      const storageKey = 'build-user-properties-demo-id-v1';
      let userId = localStorage.getItem(storageKey);
      if (!userId) {
        userId = `build-properties-${crypto.randomUUID()}`;
        localStorage.setItem(storageKey, userId);
      }
      amplitude.setUserId(userId);
      enabled = true;
      return { status: 'ready', userId, deviceId: amplitude.getDeviceId() };
    }).catch((error) => {
      console.error('Analytics initialization failed', error);
      return { status: 'error', userId: null, deviceId: null };
    });
  }
  return ready;
}

async function identifyThenTrack(operation, eventName, properties) {
  if (!enabled) return 'Analytics is disabled. Add your test-project key and reload.';
  const update = await amplitude.identify(operation).promise;
  if (update.code !== 200) throw new Error(`Property update: ${update.message}`);
  const event = await amplitude.track(eventName, properties).promise;
  if (event.code !== 200) throw new Error(`Event upload: ${event.message}`);
  return 'Property update and follow-up event accepted. Check the profile in Amplitude.';
}

export function updatePreferences(input) {
  const values = preferenceValues(input);
  return identifyThenTrack(preferenceIdentify(values), 'Preferences Updated', {
    selected_plan: values.plan, selected_theme: values.theme,
  });
}

export function clearPreferredTheme() {
  return identifyThenTrack(clearedThemeIdentify(), 'Theme Preference Cleared', {});
}
```

The SDK bundles analytics with other products. This example disables autocapture, sets replay sampling to zero, and skips guides and surveys. Analytics remote fetching is disabled so local choices apply. The shared data center and instance name stay at the top level of `initAll`.

An Identify operation updates properties; the ordinary event afterward makes the updated state available with that event. `Preferences Updated` also carries selected values as event properties, so you can compare one action's context with the user's properties at that moment. Later updates don't rewrite earlier event history.

**MCP.** Use the [Docs MCP server](https://amplitude.com/docs/amplitude-ai/docs-mcp-server) to check current Identify methods before an agent edits your implementation. It reads public documentation and doesn't access your project's user records.

## 4. Connect the property controls

I'll send updates from button handlers and guard overlapping actions. Mounting or re-rendering the component doesn't increment the counter.

src/App.jsx

```jsx
import React, { useRef, useState } from 'react';
import { updatePreferences, clearPreferredTheme } from './analytics.js';

export function App({ analytics }) {
  const [plan, setPlan] = useState('starter');
  const [theme, setTheme] = useState('dark');
  const [busy, setBusy] = useState(false);
  const pending = useRef(false);
  const [message, setMessage] = useState('Choose properties for the synthetic demo user.');
  async function run(action) {
    if (pending.current) return;
    pending.current = true; setBusy(true);
    try { setMessage(await action()); }
    catch (error) { setMessage(error.message); }
    finally { pending.current = false; setBusy(false); }
  }
  return (
    <main>
      <p className="eyebrow">USER PROPERTIES DEMO</p>
      <h1>Update a demo user</h1>
      <p>These controls change analytics properties for a synthetic user. They don't change billing, account membership, or application settings.</p>
      <label htmlFor="plan">Plan property</label>
      <select id="plan" value={plan} disabled={busy} onChange={(e) => setPlan(e.target.value)}>
        <option value="starter">Starter</option><option value="pro">Pro</option>
      </select>
      <label htmlFor="theme">Theme property</label>
      <select id="theme" value={theme} disabled={busy} onChange={(e) => setTheme(e.target.value)}>
        <option value="dark">Dark</option><option value="light">Light</option>
      </select>
      <button id="apply" disabled={busy} onClick={() => run(() => updatePreferences({ plan, theme }))}>Apply properties</button>
      <button id="clear-theme" disabled={busy} onClick={() => run(clearPreferredTheme)}>Clear theme property</button>
      <p role="status">{busy ? 'Sending...' : message}</p>
      <aside>
        <p>Analytics: <strong id="analytics-status">{analytics.status}</strong></p>
        <p>User ID: <code id="user-id">{analytics.userId ?? 'not initialized'}</code></p>
        <p>Device ID: <code id="device-id">{analytics.deviceId ?? 'not initialized'}</code></p>
      </aside>
    </main>
  );
}
```

src/style.css

```css
:root { font-family: Helvetica, Arial, sans-serif; color: #000000; background: #F2F4F8; }
body { margin: 0; }
main { max-width: 760px; margin: 40px auto; padding: 32px; background: #FFFFFF; border-radius: 16px; }
h1 { font-size: 36px; }
p { line-height: 1.5; }
.eyebrow { font-size: 12px; letter-spacing: 0.08em; }
nav { display: flex; gap: 20px; flex-wrap: wrap; padding: 16px 0; }
a { color: #0052F2; }
section, aside { border-top: 1px solid #D5D9E0; margin-top: 24px; padding-top: 24px; }
label { display: block; margin-bottom: 8px; }
button, select, [role='button'] { font: inherit; padding: 10px 14px; margin: 0 12px 12px 0; border: 1px solid #000000; border-radius: 6px; color: #000000; background: #FFFFFF; }
button, [role='button'] { cursor: pointer; }
#save-settings { color: #FFFFFF; background: #0052F2; border-color: #0052F2; }
[role='button'] { display: inline-block; }
:focus-visible { outline: 3px solid #0052F2; outline-offset: 3px; }
code { overflow-wrap: anywhere; }
@media (max-width: 800px) { main { margin: 16px; padding: 24px; } }

button:disabled, select:disabled { opacity: 0.6; cursor: wait; }
form { margin-top: 24px; }
```

The disabled-key mode leaves the interface usable and reports that analytics isn't initialized. This demo stores only its synthetic identifier locally; it doesn't implement login or account-group properties.

## 5. Mount and test the app

I'll start the app once outside the React component tree and retain Strict Mode. The tests exercise the operation or session behavior separately from the UI.

src/main.jsx

```jsx
import React, { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { App } from './App.jsx';
import { initializeAnalytics } from './analytics.js';
import './style.css';

initializeAnalytics().then((analytics) => {
  createRoot(document.getElementById('root')).render(
    <StrictMode><App analytics={analytics} /></StrictMode>,
  );
});
```

tests/properties.test.mjs

```javascript
import test from 'node:test';
import assert from 'node:assert/strict';
import { preferenceValues, preferenceIdentify, clearedThemeIdentify } from '../src/properties.js';

test('actual Identify serializes replacement, first value and counter separately', () => {
  const operations = preferenceIdentify({ plan: 'pro', theme: 'dark' }).getUserProperties();
  assert.deepEqual(operations, {
    $set: { plan: 'pro', preferred_theme: 'dark' },
    $setOnce: { first_theme: 'dark' },
    $add: { preference_updates: 1 },
  });
  assert.deepEqual(clearedThemeIdentify().getUserProperties(), { $unset: { preferred_theme: '-' } });
});

test('only fixed categories reach the operation builder', () => {
  assert.deepEqual(preferenceValues({ plan: 'starter', theme: 'light', email: 'omit@example.test' }), { plan: 'starter', theme: 'light' });
  assert.throws(() => preferenceIdentify({ plan: 'private free text', theme: 'light' }), /listed/);
  assert.throws(() => preferenceIdentify({ plan: 'pro', theme: 'unknown' }), /listed/);
});
```

Terminal

```sh
pnpm test
pnpm build
pnpm dev
```

Open the local URL printed by Vite.

## Verify it worked

Use a fresh browser context for the expected counts below, then keep the same synthetic user ID for all three actions. On a repeated run, the counter starts from its existing value; compare the increase rather than assuming zero.

1. **Local app:** Apply Starter and Dark once. Apply Pro and Light once. Clear the theme once. Each action waits for the property update and following event upload result. The UI reports HTTP acceptance separately from profile inspection.
2. **Network and extension:** Confirm upload requests return HTTP 200. Use Instrumentation Explorer to inspect the `$identify` operations and ordinary event bodies. Larger SDK bodies can be compressed, so use Network for transport status rather than relying on its payload view.
3. **User Lookup:** Search the displayed user ID and open Activity. Events normally populate in ten seconds to one minute. Open the first `Preferences Updated`: `plan` is `starter`, both themes are `dark`, and `preference_updates` is one. On the second, `plan` is `pro`, `preferred_theme` is `light`, `first_theme` is still `dark`, and the counter is two.
4. **Removal and history:** On `Theme Preference Cleared`, confirm `preferred_theme` is absent while `first_theme` and the counter remain. Reopen the earlier event to confirm its historical theme remains. Refresh the app and confirm the displayed synthetic user ID stays the same.

## Troubleshooting

### The property update is absent from a chart

Send a normal event after the Identify operation. Check the property on that following event in User Lookup; don't expect an update to change previously ingested events.

### The counter jumps by two

Check for repeated clicks, retries, a mount effect, or a second caller. Keep one additive operation per intended update and compare the corresponding Identify operations. `add` doesn't deduplicate separate business actions for you.

### The first theme never changes

That is the `setOnce` behavior. Use `set` for a property intended to change. Keep `first_theme` separate from `preferred_theme`.

### Clearing the theme changes nothing

Use a separate `Identify().unset('preferred_theme')` and follow it with an event. Don't combine `set` and `unset` on the same property in one Identify object; the SDK ignores a second operation on the same key.

### Analytics is disabled

Set the test project's ingestion key in `.env.local` and restart Vite. For a built app, rebuild it because Vite substitutes the environment variables at build time.

## Full code reference

The [complete runnable example](https://github.com/amplitude/ampli-examples/tree/6094858f8db8396891e488649ead49482dc8e1db/browser/javascript/v2/react-user-properties) includes the lockfile. These are the complete application and test files, combined for copying. Keep environment values local.

Full code reference

```text
===== package.json =====
{
  "name": "amplitude-react-user-properties",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "packageManager": "pnpm@10.33.2+sha512.a90faf6feeab71ad6c6e57f94e0fe1a12f5dcc22cd754db40ae9593eb6a3e0b6b12e3540218bb37ae083404b1f2ce6db2a4121e979829b4aff94b99f49da1cf8",
  "engines": {
    "node": ">=22.12.0",
    "pnpm": ">=10.21.0"
  },
  "scripts": {
    "dev": "vite --host 127.0.0.1",
    "build": "vite build",
    "preview": "vite preview --host 127.0.0.1",
    "test": "node --test tests/*.test.mjs"
  },
  "dependencies": {
    "@amplitude/unified": "1.2.1",
    "react": "19.3.1",
    "react-dom": "19.3.1"
  },
  "devDependencies": {
    "vite": "8.3.6"
  }

===== pnpm-workspace.yaml =====
minimumReleaseAge: 10080
trustPolicy: no-downgrade

===== .gitignore =====
node_modules/
dist/
.env
.env.local
.env.*.local

===== index.html =====
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>User properties demo</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>

===== .env.example =====
VITE_AMPLITUDE_API_KEY=
VITE_AMPLITUDE_SERVER_ZONE=US

===== src/properties.js =====
import { Identify } from '@amplitude/unified';

export function preferenceValues(input) {
  if (!['starter', 'pro'].includes(input?.plan)
    || !['light', 'dark'].includes(input?.theme)) {
    throw new Error('Choose one of the listed plans and themes.');
  }
  return { plan: input.plan, theme: input.theme };
}

export function preferenceIdentify(input) {
  const { plan, theme } = preferenceValues(input);
  return new Identify()
    .set('plan', plan)
    .set('preferred_theme', theme)
    .setOnce('first_theme', theme)
    .add('preference_updates', 1);
}

export function clearedThemeIdentify() {
  return new Identify().unset('preferred_theme');
}

===== src/analytics.js =====
import * as amplitude from '@amplitude/unified';
import { preferenceIdentify, preferenceValues, clearedThemeIdentify } from './properties.js';

let ready;
let enabled = false;

export function initializeAnalytics() {
  const apiKey = import.meta.env.VITE_AMPLITUDE_API_KEY?.trim();
  if (!apiKey) return Promise.resolve({ status: 'disabled', userId: null, deviceId: null });
  if (!ready) {
    ready = amplitude.initAll(apiKey, {
      instanceName: 'build-user-properties',
      serverZone: import.meta.env.VITE_AMPLITUDE_SERVER_ZONE === 'EU' ? 'EU' : 'US',
      analytics: { autocapture: false, remoteConfig: { fetchRemoteConfig: false } },
      sessionReplay: { sampleRate: 0 },
      engagement: { skip: true },
    }).then(() => {
      const storageKey = 'build-user-properties-demo-id-v1';
      let userId = localStorage.getItem(storageKey);
      if (!userId) {
        userId = `build-properties-${crypto.randomUUID()}`;
        localStorage.setItem(storageKey, userId);
      }
      amplitude.setUserId(userId);
      enabled = true;
      return { status: 'ready', userId, deviceId: amplitude.getDeviceId() };
    }).catch((error) => {
      console.error('Analytics initialization failed', error);
      return { status: 'error', userId: null, deviceId: null };
    });
  }
  return ready;
}

async function identifyThenTrack(operation, eventName, properties) {
  if (!enabled) return 'Analytics is disabled. Add your test-project key and reload.';
  const update = await amplitude.identify(operation).promise;
  if (update.code !== 200) throw new Error(`Property update: ${update.message}`);
  const event = await amplitude.track(eventName, properties).promise;
  if (event.code !== 200) throw new Error(`Event upload: ${event.message}`);
  return 'Property update and follow-up event accepted. Check the profile in Amplitude.';
}

export function updatePreferences(input) {
  const values = preferenceValues(input);
  return identifyThenTrack(preferenceIdentify(values), 'Preferences Updated', {
    selected_plan: values.plan, selected_theme: values.theme,
  });
}

export function clearPreferredTheme() {
  return identifyThenTrack(clearedThemeIdentify(), 'Theme Preference Cleared', {});
}

===== src/App.jsx =====
import React, { useRef, useState } from 'react';
import { updatePreferences, clearPreferredTheme } from './analytics.js';

export function App({ analytics }) {
  const [plan, setPlan] = useState('starter');
  const [theme, setTheme] = useState('dark');
  const [busy, setBusy] = useState(false);
  const pending = useRef(false);
  const [message, setMessage] = useState('Choose properties for the synthetic demo user.');
  async function run(action) {
    if (pending.current) return;
    pending.current = true; setBusy(true);
    try { setMessage(await action()); }
    catch (error) { setMessage(error.message); }
    finally { pending.current = false; setBusy(false); }
  }
  return (
    <main>
      <p className="eyebrow">USER PROPERTIES DEMO</p>
      <h1>Update a demo user</h1>
      <p>These controls change analytics properties for a synthetic user. They don't change billing, account membership, or application settings.</p>
      <label htmlFor="plan">Plan property</label>
      <select id="plan" value={plan} disabled={busy} onChange={(e) => setPlan(e.target.value)}>
        <option value="starter">Starter</option><option value="pro">Pro</option>
      </select>
      <label htmlFor="theme">Theme property</label>
      <select id="theme" value={theme} disabled={busy} onChange={(e) => setTheme(e.target.value)}>
        <option value="dark">Dark</option><option value="light">Light</option>
      </select>
      <button id="apply" disabled={busy} onClick={() => run(() => updatePreferences({ plan, theme }))}>Apply properties</button>
      <button id="clear-theme" disabled={busy} onClick={() => run(clearPreferredTheme)}>Clear theme property</button>
      <p role="status">{busy ? 'Sending...' : message}</p>
      <aside>
        <p>Analytics: <strong id="analytics-status">{analytics.status}</strong></p>
        <p>User ID: <code id="user-id">{analytics.userId ?? 'not initialized'}</code></p>
        <p>Device ID: <code id="device-id">{analytics.deviceId ?? 'not initialized'}</code></p>
      </aside>
    </main>
  );
}

===== src/style.css =====
:root { font-family: Helvetica, Arial, sans-serif; color: #000000; background: #F2F4F8; }
body { margin: 0; }
main { max-width: 760px; margin: 40px auto; padding: 32px; background: #FFFFFF; border-radius: 16px; }
h1 { font-size: 36px; }
p { line-height: 1.5; }
.eyebrow { font-size: 12px; letter-spacing: 0.08em; }
nav { display: flex; gap: 20px; flex-wrap: wrap; padding: 16px 0; }
a { color: #0052F2; }
section, aside { border-top: 1px solid #D5D9E0; margin-top: 24px; padding-top: 24px; }
label { display: block; margin-bottom: 8px; }
button, select, [role='button'] { font: inherit; padding: 10px 14px; margin: 0 12px 12px 0; border: 1px solid #000000; border-radius: 6px; color: #000000; background: #FFFFFF; }
button, [role='button'] { cursor: pointer; }
#save-settings { color: #FFFFFF; background: #0052F2; border-color: #0052F2; }
[role='button'] { display: inline-block; }
:focus-visible { outline: 3px solid #0052F2; outline-offset: 3px; }
code { overflow-wrap: anywhere; }
@media (max-width: 800px) { main { margin: 16px; padding: 24px; } }

button:disabled, select:disabled { opacity: 0.6; cursor: wait; }
form { margin-top: 24px; }

===== src/main.jsx =====
import React, { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { App } from './App.jsx';
import { initializeAnalytics } from './analytics.js';
import './style.css';

initializeAnalytics().then((analytics) => {
  createRoot(document.getElementById('root')).render(
    <StrictMode><App analytics={analytics} /></StrictMode>,
  );
});

===== tests/properties.test.mjs =====
import test from 'node:test';
import assert from 'node:assert/strict';
import { preferenceValues, preferenceIdentify, clearedThemeIdentify } from '../src/properties.js';

test('actual Identify serializes replacement, first value and counter separately', () => {
  const operations = preferenceIdentify({ plan: 'pro', theme: 'dark' }).getUserProperties();
  assert.deepEqual(operations, {
    $set: { plan: 'pro', preferred_theme: 'dark' },
    $setOnce: { first_theme: 'dark' },
    $add: { preference_updates: 1 },
  });
  assert.deepEqual(clearedThemeIdentify().getUserProperties(), { $unset: { preferred_theme: '-' } });
});

test('only fixed categories reach the operation builder', () => {
  assert.deepEqual(preferenceValues({ plan: 'starter', theme: 'light', email: 'omit@example.test' }), { plan: 'starter', theme: 'light' });
  assert.throws(() => preferenceIdentify({ plan: 'private free text', theme: 'light' }), /listed/);
  assert.throws(() => preferenceIdentify({ plan: 'pro', theme: 'unknown' }), /listed/);
});
```

## Hand it to your agent

Use this prompt to adapt the example to an existing application.

Implementation prompt

```text
Use https://amplitude.com/build/react-user-properties and its linked source.
Inspect the current SDK entry point and application flow first. Merge into existing
files; preserve auth, consent, routes, and other instrumentation. Fetch current
Amplitude docs for the installed SDK. Keep the ingestion key in the existing
environment mechanism and never add server secrets to browser code.

Use Identify to set plan/preferred_theme, setOnce first_theme, add to a demo update
counter, and unset preferred_theme in a separate operation. Keep each property
in one operation per Identify object. Track a following normal event and inspect
its processed user properties. Keep tracking out of render/mount effects.
Use the real authenticated ID when adapting; the synthetic local ID is for the demo.
Preserve event properties separately from user properties. Don't treat add as
a durable exactly-once transaction or retry it blindly.

Test blank-key startup and failure paths as well as success. Confirm real SDK
uploads and processed data separately from local tests. Report changed files and
remaining coverage limits.
```

## What this unlocks

[Product analytics](https://amplitude.com/amplitude-analytics) can segment `Preferences Updated` by the user's plan at that time.

[Session replay](https://amplitude.com/session-replay) can add visual context when separately enabled with appropriate privacy settings.

[Feature flags](https://amplitude.com/feature-management) can support a later preferences experiment, using a stable event to measure behavior after configuration.

[Guides and surveys](https://amplitude.com/guides-and-surveys) can gather feedback about the preferences experience when enabled separately.

## Frequently asked questions

### Are these event properties or user properties?

`plan`, `preferred_theme`, `first_theme`, and `preference_updates` are user properties updated through Identify. `selected_plan` and `selected_theme` belong to a single `Preferences Updated` event. Use the property type that matches the question you are analyzing.

### Does this update an account or company?

This recipe updates one user. Account-group properties and account-level reporting are a separate implementation; changing a user's `plan` property doesn't update billing or company membership.

### Should I resend every property with each event?

User property values persist after you set them and apply to later events until changed. Update them at the application lifecycle point that owns the value; keep a following event when verifying the change.

## Next steps

[Web frameworksReact product analyticsInstall analytics and track deliberate business events.](https://amplitude.com/build/react-product-analytics)[Use caseCustom events alongside autocaptureSeparate interaction capture from confirmed outcomes.](https://amplitude.com/build/react-custom-events)[Use caseStitch client and server eventsUse a consistent identity across browser and backend events.](https://amplitude.com/build/stitch-client-server-events)

Reference docs

[Install the Browser Unified SDK →](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk/get-started)[Identify reference →](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2/reference#identify)[User properties and event properties →](https://amplitude.com/docs/data/user-properties-and-events)[Instrument and configure →](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2/instrument-and-configure)[Debug analytics →](https://amplitude.com/docs/analytics/debug-analytics)[Docs MCP server →](https://amplitude.com/docs/amplitude-ai/docs-mcp-server)

Amplitude is the leading [all-in-one analytics platform](https://amplitude.com/) for building better products. Product and engineering teams use Amplitude to connect [product analytics](https://amplitude.com/amplitude-analytics) and [web analytics](https://amplitude.com/web-analytics) with [session replay](https://amplitude.com/session-replay), [heatmaps](https://amplitude.com/heatmaps), [experimentation](https://amplitude.com/amplitude-experiment), [feature flags](https://amplitude.com/feature-management), and [guides and surveys](https://amplitude.com/guides-and-surveys) in one unified workflow, with [AI agents](https://amplitude.com/ai-agents) working across all of it. Learn how Amplitude is building [self-improving products](https://amplitude.com/self-improving-products) with [Wave](https://amplitude.com/wave), helping teams turn product data into PRs.

For agents

[View raw .md](/build/react-user-properties.md)[llms.txt](/llms.txt)

## Connect the next event

Make the identity and properties explicit, then verify them in your test project.

[Create a free account](https://app.amplitude.com/signup)[Browse all Build tutorials](https://amplitude.com/build)
