Skip to content
Featsync Docs

Flag Types

Featsync supports two types of flags: Boolean and Percentage Rollout.

Boolean Flags

The simplest type - either ON or OFF for everyone.

Use Cases

  • Kill switches - Quickly disable a feature if something goes wrong
  • Feature toggles - Show/hide features based on business decisions
  • Maintenance mode - Temporarily disable functionality

Example

// Boolean flag - same result for all users
if (await featsync.isEnabled('dark-mode')) {
  enableDarkMode();
}

In the dashboard:

  • Toggle is ON → Everyone sees the feature
  • Toggle is OFF → No one sees the feature

Percentage Rollout Flags

Release features to a percentage of users. Uses consistent hashing to ensure users don’t flip-flop.

Use Cases

  • Gradual releases - Start at 10%, increase to 25%, then 50%, then 100%
  • A/B testing - Show feature to 50% of users
  • Risk mitigation - Limit blast radius of potential bugs

Example

// Percentage rollout - result depends on user
const userId = getCurrentUserId();


if (await featsync.isEnabledForUser('new-checkout', userId)) {
  showNewCheckout(); // ~25% of users see this
} else {
  showOldCheckout(); // ~75% of users see this
}

In the dashboard:

  • Set percentage to 25% → ~25% of users see the feature
  • Same user always gets the same result

Choosing a Type

ScenarioFlag Type
Enable/disable for everyoneBoolean
Emergency kill switchBoolean
Gradual feature rolloutPercentage
User-specific experiencePercentage
A/B testing (50/50)Percentage

How Percentage Rollout Works

When you use isEnabledForUser():

  1. SDK combines the flag key and user ID
  2. Generates a hash value (0-99)
  3. If hash < percentage → user is IN the rollout
  4. If hash >= percentage → user is OUT

Consistent Hashing

The same user always gets the same result:

// User "alice" checking flag "new-feature"
// Hash = 23


// If percentage is 25% → alice is IN (23 < 25)
// If percentage is 20% → alice is OUT (23 >= 20)
// If percentage is 50% → alice is IN (23 < 50)

Independence Between Flags

Different flags have different hash results for the same user:

// User "alice" might get:
// - "new-checkout": hash = 23 → IN at 25%
// - "new-pricing": hash = 67 → OUT at 25%

Creating Flags

In the Dashboard

  1. Go to Flags → Create Flag
  2. Enter name and key
  3. Choose type:
    • Boolean - Simple on/off
    • Percentage - Specify rollout %

Via API

Terminal window
# Boolean flag
curl -X POST https://api.featsync.dev/api/v1/flags \
  -H "Authorization: Bearer fs_..." \
  -d '{"name": "Dark Mode", "key": "dark-mode", "type": "boolean"}'


# Percentage flag
curl -X POST https://api.featsync.dev/api/v1/flags \
  -H "Authorization: Bearer fs_..." \
  -d '{"name": "New Checkout", "key": "new-checkout", "type": "percentage", "percentage": 25}'

Converting Between Types

You can change a flag’s type in the dashboard:

  • Boolean → Percentage: Set a percentage (e.g., 50%)
  • Percentage → Boolean: Setting to 100% effectively makes it boolean

Best Practices

Use Meaningful Names

✅ Good: "new-checkout-flow", "enable-notifications"
❌ Bad: "flag1", "test", "temp"

Start Small

For percentage rollouts, start at 5-10% and increase gradually.

Monitor After Changes

Watch error rates and user feedback whenever you change flag values.

Clean Up

Once a feature is fully rolled out, remove the flag check from your code.

Next Steps