Targeting Conditions - GrowthBook Documentation

Add targeting conditions to a rule to control which values a user sees. Conditions are evaluated against attributes you pass into the SDK — like user ID, country, plan type, or any custom property. This page covers how to set up attributes, write conditions, and use Saved Groups for reusable targeting.

Attributes

For targeting to work, you need to pass attributes into the GrowthBook SDK and define them in the GrowthBook app. Here’s a quick overview of how to do both.

Passing Attributes into the SDK

Attributes are passed into your SDKs as key-value pairs. The keys are completely customizable — use whatever fits your application’s data model. Here’s an example from the JavaScript SDK:

growthbook.setAttributes({
  id: "123",
  email: "hello@growthbook.io",
  country: "US",
  url: window.location.href,
  userAgent: navigator.userAgent,
  admin: true,
  age: 50,
});

Defining Attributes in GrowthBook

In addition to passing attributes into the SDK, define the same attribute keys in the GrowthBook app under SDK Connections → Attributes:

Attribute Values Are Never Sent to GrowthBookThe actual values of targeting attributes (e.g., user IDs, emails) are never sent to GrowthBook. They are only stored in memory locally within the SDK. This architecture keeps your users’ PII safe and secure.

Each attribute has 4 parts:

Attribute name — How the attribute is referenced in the SDK.
Data Type — The type of value the attribute holds.
Identifier — Whether this attribute uniquely identifies a person, account, company, or device. Identifiers are used for experiment assignments.
Projects — Which projects the attribute is available in. If no projects are selected, the attribute is available everywhere.

Attribute Data Types

GrowthBook supports the following attribute data types:

Data Type	Description	Example
Boolean	true or false value	`true`, `false`
Number	Floats or integers	`25`, `3.14`, `-8`
String	Freeform text	`"alice@example.com"`, `"blue"`
Enum	Short list of predefined string values	`"basic"`, `"pro"`, `"enterprise"`
Secure String	String values hashed before passing to SDK for privacy	`"secure-id-123"`
Array of Strings	List of strings, useful for tags or categories	`["admin", "editor"]`
Array of Numbers	List of numeric values	`[1, 2, 3, 5, 8]`
Array of Secure Strings	Multiple hashed string values for secure targeting	`["user123", "user456"]`

Constrained List Attributes

Array attributes (Array of Strings, Array of Numbers, Array of Secure Strings) can optionally be restricted to a fixed set of allowed values. When creating or editing an array attribute under SDK Configurations → Attributes, fill in the Allowed Values field with a comma-separated list — a user can still hold multiple values at once (e.g. ["admin", "editor"]), but each must be one of the allowed values. Once restricted, targeting conditions on that attribute use a typeahead multi-select that only accepts the allowed values (no free-form entry) and offer the includes any of / includes none of operators. Leave Allowed Values blank to keep the list unrestricted.

Changing an Attribute’s Data Type

You can change an attribute’s data type in place (including String → Enum) by editing it under SDK Configurations → Attributes. You do not need to create a new attribute or re-point features — the change is applied in place and existing targeting conditions keep evaluating, since values are stored as-is and the SDK does not enforce data types. When converting to a constrained type (Enum, or an array with Allowed Values), make sure the allowed values include every value already used in existing conditions. Conditions that reference an out-of-list value, or that use an operator no longer offered for the new type, keep running but become harder to edit. The edit modal lists the features, experiments, and condition groups that reference the attribute so you can audit them first.

Semantic Version Targeting

GrowthBook supports semantic version string comparisons, so that 1.0.10 is correctly treated as greater than 1.0.9. To use this, create or edit a String attribute under SDK Configurations → Attributes and select Version string in the format dropdown.

After saving, targeting operators (e.g., is greater than) automatically use a version-safe comparison function.

SDK CompatibilitySemantic version targeting is only supported in some SDKs. Check the release notes for your specific SDK to confirm compatibility.

Date Targeting

GrowthBook supports a date format for string attributes that makes it easier to target by date. To use this, create or edit a string attribute under SDK Configurations → Attributes and select Date string in the format dropdown.

After saving, certain targeting operators (e.g., is after or on or is equal to) display a date picker input. Dates entered with the date picker are saved as ISO-formatted date strings (e.g., 2024-07-23T20:06).

Country Code Targeting

Use 2-character ISO country codes to simplify targeting by country. To set up country code targeting:

Create an attribute and set the Data Type to String.
Change the String Format to ISO Country Code (2 letter).
Save the attribute.

When setting targeting rules, you’ll get a dropdown to select a country directly.

Defining Conditions

GrowthBook provides a visual UI for defining targeting conditions using your attributes.

By default, string attributes are case sensitive. For example, if you pass us into the SDK, it will not match US. To make string attributes case insensitive, enable the Case insensitive toggle:

Advanced Mode

For more advanced targeting, enter conditions as JSON by clicking Advanced Mode. The JSON structure uses a MongoDB-inspired query syntax. Multiple conditions are always joined with AND (except when explicitly using $or/$nor). Below are all supported operators with examples.

Simple Equality

Key/value pairs for exact matches:

{
  "attribute1": "value1",
  "attribute2": 123,
  "attribute3": false
}

Comparison Operators

Basic comparison operators for string/number attributes:

$eq (equals)
$ne (not equals)
$lt (less than)
$lte (less than or equal to)
$gt (greater than)
$gte (greater than or equal to)
$regex (regular expression match, string attributes only)
$in (in array)
$nin (not in array)

{
  "foo": {
    "$gt": 10,
    "$lte": 99
  },
  "bar": {
    "$in": ["a","b","c"]
  },
  "baz": {
    "$regex": "^test-([0-9]+)$"
  }
}

Semantic Version Operators

Comparison operators for semantic version strings:

$veq (equals)
$vne (not equals)
$vlt (less than)
$vlte (less than or equal to)
$vgt (greater than)
$vgte (greater than or equal to)

{
  "appVersion": {
    "$vgt": "1.5.6",
    "$vlte": "5.4.0"
  }
}

Array Operators

Operators for array attributes:

$elemMatch (at least one element must match the specified condition)
$all (all of the specified values must exist in the array)
$size (array length must match the specified condition)

{
  "emails": {
    "$elemMatch": {
      "$regex": "@gmail.com$"
    }
  },
  "hobbies": {
    "$all": ["hiking","tennis","chess"]
  },
  "tags": {
    "$size": {
      "$gt": 5
    }
  }
}

Miscellaneous Operators

$exists (tests if the attribute value is null or not)
$type (tests if the attribute’s type matches the type specified)
$not (inverts a nested condition)

{
  "alternateEmail": {
    "$exists": true
  },
  "foo": {
    "$type": "string"
  },
  "name": {
    "$not": {
      "$regex": "^J"
    }
  }
}

Logical Operators

Logical operators with arbitrary nesting levels:

$or
$nor
$and
$not

{
  "$or": [
    {
      "$not": {
        "foo": "abc"
      }
    },
    {
      "$and": [
        {"bar": true},
        {"baz": 123}
      ]
    }
  ]
}

MongoDB-style Query SyntaxGrowthBook uses MongoDB query syntax because it is easy to read, write, and well documented. Conditions are never executed against a database — the SDKs include a lightweight interpreter for this syntax that runs entirely locally.

Saved Groups

Saved Groups let you target the same group of users across multiple features and experiments. Define a group once and reuse it everywhere — for example, beta testers or high-value customers.

Project Scope

By default, a Saved Group’s Projects help filter the pickers. Cross-project references remain allowed by the server, including nested Condition Groups. To enforce scope on Feature Flags, enable Enforce Saved Group Project scope under Settings → SDK Configuration → Saved Group Settings. New references must then use groups that are unscoped or shared with every Project where the referencing rule can run. Existing references are preserved; expanding their delivery scope checks only the additional Projects. This includes the Feature Flag’s primary Project and targetingProjects (or All Projects), narrowed by the rule’s own Project scope. A rule delivered to All Projects requires unscoped groups. With enforcement enabled, the rule pickers apply this Project scope and keep existing selections visible. Validation follows the entire nested Saved Group graph, including $savedGroups, $inGroup, and $notInGroup. Nested groups do not need to cover their parent group’s scope: each is checked against the consuming Feature Flag’s evaluation scope. For example, a group shared with Projects A and B can reference a group shared only with B when the consuming rule runs only in B. When enforcement is enabled, the server checks rule writes and publication, including Project moves and restored revisions. Ramp plans validate new Saved Group references when saved, before a step runs. Restoring a ramp’s saved starting state or an earlier step preserves its existing targeting. Changing a Saved Group’s Projects or nested references is blocked if it introduces a scope violation for a consuming Feature Flag or active Feature Flag draft, including archived Feature Flags. Saved Group drafts are checked against their consumers when published. Update the references or share the groups with the required Projects first. Feature publication and bulk-release planning report scope failures as blocking gates. Warning and schema-validation overrides do not bypass this organization policy. Enabling enforcement does not rewrite existing targeting or remove groups from SDK payloads. References already stored in live Feature Flags and drafts continue to work through ordinary edits and publication, even if they are outside their groups’ Project scope. New references (including references in new rules) and additional delivery Projects are validated. Combining a draft reference with new targeting Projects during a merge is also checked. This setting applies to Feature Flag targeting; standalone experiment targeting is unchanged.

Condition Groups

Define targeting rules based on user attributes. For example, target users who are located in the US and on a mobile device.

Saved groups condition, showing how to add a US user on a mobile device

ID Lists

Manually define targeted users via text input or by uploading a CSV. For example, create a beta testers group by uploading a CSV of user IDs.

Saved Group UI, focusing on adding an ID list

ID Lists are limited to 1 MB. Using multiple large ID Lists may impact performance as it increases the SDK payload. Keep ID Lists as concise as possible. ID Lists accept the following attribute types: string, secureString, or number. For targeting other types of attributes, use Condition Groups.

Passing Saved Groups by referenceEnterprise users can reduce payload size by passing Saved Groups by reference: each group is sent once in the payload instead of being copied into every rule that uses it. Edit your SDK Connection and set Pass Saved Groups by reference to ID Lists only or All Saved Groups. All Saved Groups needs a newer SDK version, such as JavaScript SDK 1.8.0 or later. If the setting isn’t visible, your SDK version does not support it.

For more advanced targeting based on the state of other feature flags, see Prerequisite Features.

Legacy behavior for empty ID listsEmpty lists would previously be ignored in the SDK payloads, causing targeting conditions referencing those lists to always evaluate to true. ID Lists created after the behavior was changed properly use the empty list, so rules checking whether a value is in the list always evaluate to false. Lists created before the change preserve the old behavior so as not to break existing features.To make an ID list with the legacy behavior evaluate to false instead of true, add a single placeholder value such as "" or ”_” so that the list isn’t empty.

​Attributes

​Passing Attributes into the SDK

​Defining Attributes in GrowthBook

​Attribute Data Types

​Constrained List Attributes

​Changing an Attribute’s Data Type

​Semantic Version Targeting

​Date Targeting

​Country Code Targeting

​Defining Conditions

​Advanced Mode

​Simple Equality

​Comparison Operators

​Semantic Version Operators

​Array Operators

​Miscellaneous Operators

​Logical Operators

​Saved Groups

​Project Scope

​Condition Groups

​ID Lists

Attributes

Passing Attributes into the SDK

Defining Attributes in GrowthBook

Attribute Data Types

Constrained List Attributes

Changing an Attribute’s Data Type

Semantic Version Targeting

Date Targeting

Country Code Targeting

Defining Conditions

Advanced Mode

Simple Equality

Comparison Operators

Semantic Version Operators

Array Operators

Miscellaneous Operators

Logical Operators

Saved Groups

Project Scope

Condition Groups

ID Lists