Deprecating


This document describes the process of deprecating props and components in our library. All kinds of deprecations should be documented in the CHANGELOG and in the relevant migration guides, both for specific components and releases.


Using the deprecationLog

The deprecationLog is an internal utility function used to log deprecation messages. Call it only when the deprecated behavior is being used. For example, when deprecating components, call deprecationLog in one of the following, depending on whether it's a class or a functional component:

  • The constructor
  • componentDidMount
  • useEffect.

Similarly, when deprecating props, call deprecationLog only when the prop is used, for example in one of the following:

  • render
  • componentDidUpdate
  • useEffect.

Removing Components

We should deprecate components when they are unnecessary (for example, when there's a better replacement) or when we've drastically changed their API or design. Since deprecating components may result in breaking changes, this should be done gradually with backward compatibility.

When planning to remove a component from the library, keep it in position and add a deprecation message. As users may still use the component, we suggest keeping its path the same (for example, src/ComponentName).

When planning to introduce a new component that may break the existing API, move the old component to the src/Deprecated folder. Then, add your new component in the same path as the old component, and add a feature flag to determine which component to use. You can see an example of this logic here. In the example, the feature flag is this part:

Copy

In the component constructor, call deprecationLog with a useful message regarding the deprecation of the component, explaining the required next steps:

Copy

Additionally, move the component's story to the Deprecated section and the stories/Deprecated folder, and update the story with a deprecation message.

Deprecated components will be removed in the next major version. After the components are removed, make sure to document these changes in the release's migration guide!

Do not forget to find all internal usages and update them accordingly.


Deprecating prop values

Deprecate props in specific cases like naming changes or when the expected value for that prop changes.

First, update the component's type definitions to reflect the new values.

Then, use the deprecationLog inside the component when the deprecated prop value is used, and add backward compatibility:

Copy

When releasing a new major version, remove the above checks and the deprecationLog from the component. Make sure to document the change in the release's migration guide!

Do not forget to find all internal usages and update them accordingly.






Last updated: 15 October 2026

Did this help?