Rules & Overrides

Contextual rules

Rules are functions evaluated reactively. Priority: below URL overrides and setFlag, above loader/static.

app.use(FeatureToggles, {
  rules: {
    darkMode: () => window.matchMedia('(prefers-color-scheme: dark)').matches,
    liveChatWidget: () => {
      const h = new Date().getHours()
      return h >= 9 && h < 18
    },
    devFeatures: () => document.cookie.includes('internal=1'),
  },
})

Rules can be overridden by setFlag() or a URL param.

URL overrides

When urlOverrides: true, query params override flag values without a page reload.

https://app.example.com/?feature:newDashboard=true&feature:checkoutFlow=v2

Variable overrides:

?feature-var:newCheckout:maxItems=10

Custom prefix (urlPrefix: 'ft'):

?ft:newDashboard=true

Priority order (highest → lowest)

URL override → runtime setFlag() → rules → loader → static flags → defaultValue

Persistent overrides

By default setFlag lives in memory only. Pass { persist: true } to save to localStorage:

const { setFlag, clearPersistedFlags, isPersisted } = useFeatureProvider()

setFlag('darkMode', true, { persist: true })
// Value survives page reloads

isPersisted('darkMode') // → true

clearPersistedFlags() // remove all persisted overrides

Override profiles

Named sets of overrides stored in localStorage — useful for QA, demos, and design reviews.

const { saveProfile, loadProfile, listProfiles } = useFeatureProvider()

saveProfile('demo-mode', {
  newDashboard: true,
  betaSearch: true,
  maintenanceMode: false,
})

loadProfile('demo-mode') // applies all flags from the profile as runtime overrides
loadProfile('default') // resets to original values (calls resetAll)

listProfiles() // → ['demo-mode']

The <FeatureDevTools> panel shows a profile dropdown when profiles exist.