A flag rule is a conditional expression that determines which users see which variant of a feature flag. Instead of treating every user the same, a flag rule evaluates attributes of the current user or context (country, device type, user segment, account age) and returns the appropriate flag variant. Rules are what make feature flags targeted rather than binary.
Without rules, a flag is a global switch: on for everyone or off for everyone. With rules, the same flag can show variant A to users in Sweden, variant B to users in the US, and the control experience to everyone else. Rules are how teams run region-specific rollouts, internal dogfooding, beta programs, and percentage-based experiments through a single flag.
How do flag rules work?
A flag rule consists of conditions and an outcome. The conditions evaluate properties of the request context: user attributes, device properties, geographic data, or custom properties that the application passes to the flag evaluation. If the conditions match, the rule returns its assigned variant.
Rules are evaluated in order. The first matching rule wins. If no rule matches, the flag returns its default variant. This ordering matters because it lets teams layer targeting logic: "if internal employee, show the experimental variant; if beta tester, show the staged variant; otherwise, show the control."
In Confidence, flag rules operate on the same structured flag configuration that defines the flag's typed properties. Because flags in Confidence can carry multiple typed properties (a color, a string, a number) in a single flag, rules control the full set of properties at once. A rule that targets beta testers doesn't just flip a boolean. It delivers the entire configuration variant: all the properties, with their correct types, in one evaluation.
Flag evaluation in Confidence happens in-process at 10 to 50 microseconds, including rule evaluation. Rules don't add network calls or meaningful latency. The SDK has the full rule configuration loaded locally and evaluates everything in-memory.
What types of targeting do flag rules support?
User attribute targeting. Target based on properties of the user: account type, subscription tier, language preference, signup date. "Show the new onboarding flow to users who signed up after January 1" is a user attribute rule.
Percentage-based targeting. Allocate a percentage of traffic to each variant. This is how rollouts work: 10% of users get the new experience, 90% get the old one. The percentage allocation is deterministic (based on a hash of the user ID), so the same user consistently sees the same variant.
Segment targeting. Target predefined user segments: "internal employees," "enterprise customers," "users in the EU." Segments abstract away the underlying attribute logic, making rules easier to read and maintain.
Context-based targeting. Target based on properties of the request rather than the user: device platform (iOS vs. Android), app version, time of day, geographic region. "Enable the feature only on iOS 18+" is a context rule.
Most real-world flag configurations combine these types. A rollout might use a percentage rule for the general population plus a segment rule that gives internal employees 100% access to the new variant for dogfooding.
What goes wrong with flag rules?
Rule complexity. As teams add targeting conditions, rules can become hard to reason about. A flag with twelve rules targeting different combinations of country, platform, and user segment requires careful ordering and testing. If the rules are complex enough that the team can't quickly answer "what does user X see?", the rules need simplifying.
Stale rules. A rule that targeted beta testers during a launch phase might still be active months later, after the feature rolled out to everyone. Like flag debt, rule debt accumulates when teams add rules and forget to clean them up. The rule keeps evaluating on every request, and if the targeted segment changes meaning over time, the behavior can diverge from the original intent.
Missing default behavior. If the rule set doesn't cover all possible users, the default variant applies. Teams sometimes forget to configure the default, or configure it as "off" when it should be "on" for a shipped feature. Always verify what happens when no rule matches.