# How to install ODS Stencil components

## Install `ods` components (webcomponents made with Stencil)

You can now type in your console :

```sh
yarn add @ovhcloud/ods-core @ovhcloud/ods-stencil @ovhcloud/ods-theme-blue-jeans
```
or
```sh
npm install --save @ovhcloud/ods-core @ovhcloud/ods-stencil @ovhcloud/ods-theme-blue-jeans
```

## Import the theme

you need to import a theme for displaying correctly all the components.
It defines all the colors, typographies, sizes etc.
the default theme is `blue-jeans` but you can build yours.

via HTML:

```html
<link rel="stylesheet" src="./node_modules/@ovhcloud/ods-theme-blue-jeans/index.css" />
```

via ES import:

```javascript
import '@ovhcloud/ods-theme-blue-jeans/index.css';
```

via css import:
```css
@import '~@ovhcloud/ods-theme-blue-jeans/index.css';
```

## Assets

### Ods-flag
You would like to use the flags in your application, please note you will have to use the flags from ODS.

Here is the package you will need: `@ovhcloud/ods-stencil/components/flag/dist/flags`

You have to copy the flags svg where you need them in your application.

First, you have to setup ods before using it by calling odsSetup in your application:

```typescript
import { odsSetup } from '@ovhcloud/ods-core';
odsSetup();
```

Then, you have to call Ods.instance().assetPath();
```typescript
Ods.instance().assetPath(`path/`);
```

## Import components

> ⚠️️ **Please note**<br />
> odsSetup must be strictly called before using any component.
> ```typescript
  import { odsSetup } from '@ovhcloud/ods-core';
  odsSetup();
  ```

You can import independently some components **built in es2017**:

`@ovhcloud/ods-stencil/components/button`

or importing the entire bundle **built in es5** (Recommended way):

`@ovhcloud/ods-stencil/components`

### For React framework

If you are using React as framework, we recommend to use the components built for React.
They are available independently for each ODS component:
`@ovhcloud/ods-stencil/components/button/react`

Or for the entire collection (recommended):
`@ovhcloud/ods-stencil/components/react`

These components are compatible with:
- React v16.8+
- TypeScript 3.7+

More information on React generated components with the component builder [stenciljs](https://stenciljs.com/docs/react)

Don't hesitate to use a **Starter**: you can download a sample application made with `React`. See `Starters` page.

### For Vue framework

If you are using VueJs as framework, we recommend to use the components built for Vue.
They are available independently for each ODS component:
`@ovhcloud/ods-stencil/components/button/vue`

Or for the entire collection (recommended):
`@ovhcloud/ods-stencil/components/vue`

These components are compatible with:
- Vue 3
- TypeScript 4

More information on React generated components with the component builder [stenciljs](https://stenciljs.com/docs/vue)

Don't hesitate to use a **Starter**: you can download a sample application made with `Vue`. See [Starters](/story/code-starters-vue-vite--page) page.

### dist

If you want to use it in vanillaJs, you can import independently some components in an HTML script tag:

- ES module: `@ovhcloud/ods-stencil/components/button/dist/ods-button/ods-button.esm.js`
- no module: `@ovhcloud/ods-stencil/components/button/dist/ods-button/ods-button.js`

or importing the entire bundle:

- ES module: `@ovhcloud/ods-stencil/components/dist/ods-stencil/ods-stencil.esm.js`
- no module: `@ovhcloud/ods-stencil/components/dist/ods-stencil/ods-stencil.js`

_example via HTML for entire bundle:_

```html
<!--  ES module via dist -->
<script type="module" src="./node_modules/@ovhcloud/ods-stencil/components/dist/ods-stencil/ods-stencil.esm.js"></script>
<!--  no module via dist -->
<script nomodule src="./node_modules/@ovhcloud/ods-stencil/components/dist/ods-stencil/ods-stencil.js"></script>
```

see more here: https://stenciljs.com/docs/javascript

### loader

For framework like vue, you can import components via a loader.
It is also the recommended way if you want IE11 and Edge support with these stencil build made components.

you can import independently some components:

- ES5 module: `@import { applyPolyfills, defineCustomElements } '@ovhcloud/ods-stencil/components/button/loader/index.js';`
- ES2017 module: `@import { applyPolyfills, defineCustomElements } '@ovhcloud/ods-stencil/components/button/loader/index.es2017.js';`

or importing the entire bundle:

- ES5 module: `@import { applyPolyfills, defineCustomElements } '@ovhcloud/ods-stencil/components/loader/index.js';`
- ES2017 module: `@import { applyPolyfills, defineCustomElements } '@ovhcloud/ods-stencil/components/loader/index.es2017.js';`

then bind custom element to the window :

```javascript
applyPolyfills().then(() => {
  defineCustomElements();
});
```

_Example via HTML for entire bundle:_

```html
<!-- ES2017 module via loader -->
<script type="module">
  import { defineCustomElements, applyPolyfills } from './node_modules/@ovhcloud/ods-stencil/components/loader/index.es2017.js';
  applyPolyfills().then(() => {
    defineCustomElements();
  });
</script>
```

see more here :

- https://stenciljs.com/docs/react
- https://stenciljs.com/docs/vue
- https://stenciljs.com/docs/javascript

### custom-elements

You can import components as custom elements in the new way of stencil team.
it is more optimized (tree shaking for instance), and the recommended way with framework integrations.

**No lazy loading**: this may be preferred for projects that are already handling bundling,
lazy-loading and defining the custom elements themselves.

**Old browser support**: not available, prefer using the **dist** to import the components.

there is no **defineCustomElements**: you have to define the imported components yourself.

you can import independently some components:

```javascript
import { OsdsCart, OsdsCartItem } from '@ovhcloud/ods-stencil/components/cart/custom-elements';
import { OsdsButton } from '@ovhcloud/ods-stencil/components/button/custom-elements';

// define the component and his sub components :
customElements.define('osds-button', OsdsButton);
customElements.define('osds-cart', OsdsCart);
customElements.define('osds-cart-item', OsdsCartItem);
```

or importing the entire bundle:

```javascript
import { OsdsCart, OsdsCartItem, OsdsButton } from '@ovhcloud/ods-stencil/components/custom-elements';

// define all the components and his sub components :
customElements.define('osds-button', OsdsButton);
customElements.define('osds-cart', OsdsCart);
customElements.define('osds-cart-item', OsdsCartItem);
```

see https://stenciljs.com/docs/custom-elements

### custom-elements-bundle (Deprecated)

> Deprecated: stenciljs deprecated this type of bundle. You should migrate to the [custom-elements](#custom-elements) way.
> **It will be removed in a future major release**

You can import components as custom elements in the deprecated way of stencil team (bundled in one file).
This may be preferred for projects that will handle bundling, lazy-loading and defining the custom elements themselves.

**No lazy loading**: this may be preferred for projects that are already handling bundling,
lazy-loading and defining the custom elements themselves.

**Old browser support**: not available, prefer using the **dist** to import the components.

you can import independently some components:

```javascript
import { OsdsCart, OsdsCartItem, defineCustomElements as defineForCart } from '@ovhcloud/ods-stencil/components/cart/custom-elements-bundle';
import { OsdsButton, defineCustomElements as definedForButton } from '@ovhcloud/ods-stencil/components/button/custom-elements-bundle';

// define the component and his sub components :
customElements.define('osds-button', OsdsButton);
customElements.define('osds-cart', OsdsCart);
customElements.define('osds-cart-item', OsdsCartItem);
// or automatically :
defineForCart();
definedForButton();
```

or importing the entire bundle:

```javascript
import { OsdsCart, OsdsCartItem, OsdsButton, defineCustomElements } from '@ovhcloud/ods-stencil/components/custom-elements-bundle';

// define all the components and his sub components :
customElements.define('osds-button', OsdsButton);
customElements.define('osds-cart', OsdsCart);
customElements.define('osds-cart-item', OsdsCartItem);
// or automatically :
defineCustomElements();
```

see more on https://stenciljs.com/docs/custom-elements-bundle