Sticky Bucketing

What is Sticky Bucketing?

When GrowthBook assigns a user to a variation, it uses a deterministic hash of the user ID. This means the same user always lands in the same bucket — as long as the experiment configuration stays the same. The problem arises when something does change.

Imagine you start an experiment at 100% traffic with a 50/50 split between control and variant. A week later, you reduce traffic to 50% to limit exposure. Users who were previously in variant may now fall outside the experiment window entirely, or worse, be reassigned to control. Their experience has silently flipped — corrupting your data and delivering an inconsistent product.

Sticky bucketing solves this by recording each user’s initial variation assignment and replaying it on every subsequent evaluation, regardless of how the experiment configuration changes.

The sticky bucket service

GrowthBook exposes a stickyBucketService option on the SDK constructor. You provide a storage backend — the SDK ships with LocalStorageStickyBucketService for browser environments — and the SDK handles reading and writing assignments automatically.

When a user is first bucketed, the SDK writes a record such as { experimentKey: "my-experiment", variationKey: "variant" } to the store. On the next page load the SDK reads this record and skips the hash calculation entirely, returning the stored variation.

When do you need sticky bucketing?

Sticky bucketing matters most in these situations:

Long-running experiments — users return many times over days or weeks. Without sticky bucketing, any configuration edit creates a pool of users who have seen both variations.
Changing traffic splits mid-experiment — reducing or increasing the percentage of users included can shift bucket boundaries and re-assign existing users.
Gradual rollouts that overlap with experiments — if you are slowly increasing traffic while simultaneously running an experiment, bucket boundaries shift with every increase.
Multi-session user journeys — when a user starts a funnel in one session and completes it in another, consistency across sessions is critical for accurate attribution.

Enabling sticky bucketing in the SDK

Pass a stickyBucketService instance when constructing GrowthBook. The example below uses LocalStorageStickyBucketService, which persists assignments in the browser’s localStorage.

import { GrowthBook, LocalStorageStickyBucketService } from '@growthbook/growthbook';

const gb = new GrowthBook({
  apiHost: 'https://cdn.growthbook.io',
  clientKey: 'sdk-YOUR_KEY',
  stickyBucketService: new LocalStorageStickyBucketService(),
});

await gb.init({ timeout: 2000 });

// Now a user assigned to 'variant' stays in 'variant'
// even if you later reduce traffic from 100% to 50%.
const result = gb.run({
  key: 'my-experiment',
  variations: ['control', 'variant'],
});

console.log('Variation:', result.value);