Skip to main content

​
React — Set person properties

Update user properties without changing the distinct ID. Use setPersonProperties to overwrite properties or setPersonPropertiesOnce to set them only if not already set. Access these methods via useSignal().

​
Accessing the methods

Get setPersonProperties and setPersonPropertiesOnce from useSignal(): 
import { useSignal } from '@signal-js/react';

function UserProfile({ user }) {
  const { setPersonProperties, setPersonPropertiesOnce } = useSignal();

  const handlePlanUpgrade = () => {
    setPersonProperties({ plan: 'pro', role: 'admin' });
  };

  const handleSignup = () => {
    // Only set if not already set (e.g. first-time signup)
    setPersonPropertiesOnce({ signupSource: 'organic', firstPurchaseDate: new Date().toISOString() });
  };

  return (
    <div>
      <button onClick={handlePlanUpgrade}>Upgrade Plan</button>
      <button onClick={handleSignup}>Complete Signup</button>
    </div>
  );
}

​
setPersonProperties(properties)

Sets or updates user properties (overwrites existing). Sends a $set event.
ParameterTypeRequiredDescription
propertiesRecord<string, unknown>yesUser properties to set or update
When to use: Update user properties after initial identification (e.g. plan changes, role updates, preference changes). 
const { setPersonProperties } = useSignal();

// Update user plan
setPersonProperties({ plan: 'enterprise', seats: 50 });

​
setPersonPropertiesOnce(properties)

Sets user properties only if they are not already set. Sends a $set_once event.
ParameterTypeRequiredDescription
propertiesRecord<string, unknown>yesUser properties to set (only if not already set)
When to use: One-time attributes that shouldn’t be overwritten (e.g. signupSource, firstPurchaseDate, referralCode). 
const { setPersonPropertiesOnce } = useSignal();

// Set signup source only if not already set
setPersonPropertiesOnce({ signupSource: 'organic' });

​
Differences from identify()

  • identify(distinctId, traits) — Changes the user’s distinct ID and sets properties. Use after login or when you know the user’s identity.
  • setPersonProperties(properties) — Updates properties without changing the distinct ID. Use when properties change after identification.
  • setPersonPropertiesOnce(properties) — Sets properties only if not already set. Use for immutable attributes.

​
See also