import { Meta } from '@storybook/addon-docs';

<Meta title="Docs/Customization/Custom components" />

# Custom components
<br />

The Plaza theme enables you to create themes using our React components library, which is included in the latest sfb-toolkit version. The toolkit includes components that you can use to quickly build and customize your storefront pages through the Storefront Builder visual editor. For example, you can integrate the `Slider`, `Carousel`, `ProductBanner`, and many more components with your Plaza theme.

If none of the components in our library suit your needs, you can create custom components. Custom components are components that you can create and customize through the [schema](?path=/docs/docs-customization-schema--docs) object.

The `Getting Started` section contains everything you need to know to start building your custom components according to our guidelines and best practices.

## Installation

<div style={{color: "red"}}><b>Note:</b> Once custom components are installed there is currently no command to automatically reverse the action! See below for instructions
on how to manually remove them.</div>

To setup your theme to use custom components, execute the following `sfb-toolkit` commands:
<li><code>sfb-toolkit components</code></li>
<br />

### sfb-toolkit components

```
sfb-toolkit components
```

The above command will setup the `current` theme such that you can create your own custom components. When you run the command, the toolkit:

- Installs a version of <a href="https://www.npmjs.com/package/@appdirect/sfb-theme-components">@appdirect/sfb-theme-components</a> in 
your current theme. <b>The version installed depends on the toolkit version</b>. Older toolkit versions will install older versions of <a href="https://www.npmjs.com/package/@appdirect/sfb-theme-components">@appdirect/sfb-theme-components</a>.

- Creates a <b>customComponents</b> folder in your current theme with two <b>AtomsShowcase</b> components as examples.

- Bundles both <b>sfb-theme-components</b> and custom components into one package in the current theme assets folder.


By default, the `sfb-theme-components` library is bundled and deployed in a CDN (Content Delivery Network) and referenced in your theme. To use custom components, `sfb-theme-components` is bundled together with the user-defined custom components into a single package.

Therefore, when you run `sfb-toolkit components`, the toolkit creates a `customComponents` folder in your current theme where you can start building custom components. Then, when you start your sfb-toolkit server with the `sfb-toolkit start` command and you make a change inside your `customComponents` folder, the toolkit bundles your components into a single package and puts it in your theme assets folder so you can preview the changes in your browser using hot module replacement.

### sfb-toolkit storybook

```
sfb-toolkit storybook
```

This command enables theme developers to visualize all available component documentation through Storybook UI. The Storybook includes both `sfb-theme-components` and the custom components that you have created.

## Reuse existing <i>sfb-theme-components</i>

You can reuse existing components (atoms or components) from the library for your custom components. For example, if you want to reuse the `Button` atom in your custom component, add the following import:

```jsx
import Button from '@appdirect/sfb-theme-components/src/atoms/button/Button';
```

For each component documented in Storybook UI, you can find under `Usage Example` an example of how you can reuse/import one of our components in your custom components.

## Remove custom components usage (manual steps)

To stop using custom components and use instead the CDN version of <a href="https://www.npmjs.com/package/@appdirect/sfb-theme-components">@appdirect/sfb-theme-components</a> (instead of the `npm` module one) please follow these steps:
<li>
    In the <code>base.html</code> file replace:
    <ol>
        <li>
            <code>{`<link rel="stylesheet" type="text/css" href="{{ r("/assets/js/components/sfb-components.css") }}">`}</code> with
            <code>{`<link rel="stylesheet" type="text/css" href="{{ config.channelSettings.channelCanonicalBaseUrl }}/sfb-theme-components@0/sfb-components.css">`}</code>
        </li>
        <li>
            <code>{`<script src="{{ r("/assets/js/components/sfb-components.js") }}"></script>`}</code> with
            <code>{`<script src="{{ config.channelSettings.channelCanonicalBaseUrl }}/sfb-theme-components@0/sfb-components.js"></script>`}</code>
        </li>
    </ol>
</li>
<li> 
    In the theme folder:
    <ol> 
        <li>
            Delete the <code>customComponents</code> folder.
        </li>
        <li>
            Using a <code>terminal</code> execute <code>npm uninstall @appdirect/sfb-theme-components --save</code>.
        </li>
    </ol>
</li>

```
    npm uninstall @appdirect/sfb-theme-components --save
```


## Update custom components UI library (sfb-theme-components)

When `sfb-toolkit components` is executed a <b>specific version</b> of `sfb-theme-components` will be installed as part of your theme and will not change. This is done to ensure that the expected behaviour
is not changed through future updates. As such, the installed `sfb-theme-components` library version is effectively `fixed`. 

To update the `sfb-theme-components` library you can simply execute `sfb-toolkit install @appdirect/sfb-theme-components@latest`.

```
    sfb-toolkit install @appdirect/sfb-theme-components@latest
```

<div style={{color: "red"}}>
<b>Note:</b> There is a possibility that your theme might not be compatible with the latest version of <code>{`sfb-theme-components`}</code> before attempting the upgrade please check
the <code>package.json</code> file and note down the <code>{`sfb-theme-component`}</code> version you are currently using so that you can revert back to it in cases you encounter any issues.
</div>

To revert back to an older `sfb-theme-components` version `sfb-toolkit install @appdirect/sfb-theme-components@version` where `version` represents the previously noted down npm package version number.

```
    sfb-toolkit install @appdirect/sfb-theme-components@version
```

## Availability

`@appdirect/sfb-toolkit@5.0.4`
