overview.stories.mdx

import { Meta } from '@storybook/blocks';

Feature Flags

Source code

{/* prettier-ignore-start /} {/ START doctoc generated TOC please keep comment here to allow auto update /} {/ DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE */}

Table of Contents

• Current feature flags
• Turning on feature flags in Javascript/react
• Turning on feature flags in Sass

{/* END doctoc generated TOC please keep comment here to allow auto update /} {/ prettier-ignore-end */}

The @carbon/react codebase ships with a number of feature flags. These feature flags enable new behavior and styling, allowing you to opt-in to new (and sometimes breaking) changes while using the current version. A feature flag may be configured in javascript, sass, or both.

This section in the storybook documents each feature flag that is available and how to configure it. Folders and stories within this section in storybook show components with all feature flags turned on.

Current feature flags

Flags prefixed with enable-* contain features we'd like consuming projects to test and give us feedback on. They're generally stable and unlikely to change but may change based on your feedback.

Flags prefixed with enable-v12-* are stable and won't change. They will be marked as true or "on" by default in the next major version, v12.

For more details on this approach, see the feature flag documentation in the Carbon monorepo.

Flag	Description	Default	Javascript flag	Sass flag
enable-experimental-tile-contrast	Enable the improved styling for tiles that provides better contrast	false		✅
enable-experimental-focus-wrap-without-sentinels	Enable the new focus wrap behavior that doesn't use sentinel nodes	false	✅
enable-treeview-controllable	Enable the new TreeView controllable API	false	✅
enable-v12-tile-default-icons	Enable default icons for Tile components	false	✅
enable-v12-overflowmenu	Enable the use of the v12 OverflowMenu leveraging the Menu subcomponents	false	✅
enable-v12-tile-radio-icons	Enable rendering of default icons in the tile components	false	✅	✅
enable-v12-structured-list-visible-icons	Enable icon components within StructuredList to always be visible	false		✅

Turning on feature flags in Javascript/react

Use the FeatureFlag component to turn on a feature flag for a portion of your application's react tree. Multiple feature flags can be configured at the same time.

import { unstable_FeatureFlags as FeatureFlags } from '@carbon/react';

<FeatureFlags
  flags={{
    'enable-v12-tile-default-icons': true,
    'enable-a-second-feature-flag': true,
  }}>
  <Tile />
</FeatureFlags>;

The FeatureFlag component can be placed at any point in your react tree and will impact all children components. You can turn on feature flags for your entire app, or only certain pages/routes/sections of your application.

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { unstable_FeatureFlags as FeatureFlags } from '@carbon/react';
import App from './App';

const root = createRoot(document.getElementById('root'));
root.render(
  <StrictMode>
    <FeatureFlags flags={{ 'enable-v12-tile-default-icons': true }}>
      <App />
    </FeatureFlags>
  </StrictMode>
);

Turning on feature flags in Sass

In Sass, you can enable feature flags in any of your stylesheets. Most often this is done at the root/entrypoint stylesheet.

@use '@carbon/react/scss/feature-flags' with (
  $feature-flags: (
    'enable-experimental-tile-contrast': true,
  )
);
@use '@carbon/react';

Feature flags can also be enabled via the provided enable() mixin

@use '@carbon/react/scss/feature-flags';
@use '@carbon/react';

@include feature-flags.enable('enable-experimental-tile-contrast');