> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Deprecating a Component

## Article: Deprecating a Component

## Article Link: https://dev.wix.com/docs/wix-design-system/contributing/deprecating-a-component.md

## Article Content:

<!-- heading -->

# Deprecating

<!-- end heading -->

<br />

> 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](invalid-url). In the example, the feature flag is this part:

<!-- grid layout -->

<!-- grid layout item -->

<!-- grid layout content -->

```jsx
render() {
  ... // Other code

  return (
    (this.props.upgrade && <ButtonNew {...rest} />) || <ButtonOld {...rest} /> // Feature flag
  );
}
```

<!-- end grid layout -->

<!-- end grid layout item -->

<!-- end grid layout content -->

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

<!-- grid layout -->

<!-- grid layout item -->

<!-- grid layout content -->

```jsx
import deprecationLog from '../utils/deprecationLog';

// ...

class IconWithOptions extends React.Component {
  constructor(props) {
    super(props);

    deprecationLog(
      `Using "<IconWithOptions/>" is deprecated. Use the newer "<DropdownBase/>" component instead, and check its documentation.`,
    );
  }
}
```

<!-- end grid layout -->

<!-- end grid layout item -->

<!-- end grid layout content -->

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:

<!-- grid layout -->

<!-- grid layout item -->

<!-- grid layout content -->

```jsx
import deprecationLog from '../utils/deprecationLog';

// ...

class SomeComponent extends React.Component {
  render() {
    let { size } = this.props;

    // Do the same thing when `size === 'little'` and `size === 'big'`
    if (size === 'medium') {
      deprecationLog(
        '<SomeComponent/> prop "size" with value "medium" is deprecated and will be removed in next major release, please use "normal" size instead',
      );

      // Making it backward compatible
      size = 'normal';
    }

    return <div>...</div>;
  }
}
```

<!-- end grid layout -->

<!-- end grid layout item -->

<!-- end grid layout content -->

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._

<br>
<br>
<br>
<br>
<br>