npm package: @spins/react-locator
Description: OCL 2.0 Locator & Widget installation for React and Next.js applications.
Latest version: 1.0.0

# SPINS React Locator

OCL 2.0 Locator & Widget installation for React and Next.js applications.

## Install

You can install this package using the package manager of your choice:

```
npm install --save @spins/react-locator
```

```
yarn add @spins/react-locator
```

```
pnpm add @spins/react-locator
```

## Usage

The most basic usage of this package is shown below, see the [Configuration](#Configuration) section for more details.

### Locator

```tsx
import { DestiniLocator, DestiniLocatorType } from '@spins/react-locator'

function Locator() {
  return <DestiniLocator
    locatorId="4442"
    alphaCode="115A"
    locatorType={DestiniLocatorType.ProductFirst}
  />
}

export default Locator
```

### Widget

```tsx
import { DestiniWidget } from '@spins/react-locator'

function Widget() {
  return (
    <DestiniWidget
      locatorId="3559"
      alphaCode="DE7"
      APO="999000000001,999000000002"
    />
  )
}

export default Widget
```

## Configuration

Each component comes with a set of configurable properties that are be to control and further customize the Locator or
Widget.

### Shared

| Property Name | Type                             | Required | Description                                                                                                                                                                                                                                                                                        |
|---------------|----------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| locatorId     | number &#124; string             | ✅        | The locator's `ID` value from the dashboard or installation script                                                                                                                                                                                                                                 |
| alphaCode     | string                           | ✅        | The locator's `alphaCode` from the dashboard or installation script                                                                                                                                                                                                                                |
| environment   | DestiniEnvironment &#124; string | ❌        | Controls the URL where the javascript file will be loaded from. Excluding this property defaults to our Production environment.<br/><br/>For compatability purposes this property will accept any string but it is highly recommend to always use the `DestiniEnvironment` type for this property. |
| APO           | string &#124; string[]           | ❌        | Limits which products display in the Locator/Widget to ones with a matching `UPC` or `GTIN` value. If passing multiple values you can either use the array syntax or separate each entry with a comma.                                                                                             |
| APOG          | string &#124; string[]           | ❌        | Limits which products display in the Locator/Widget to ones which are a part of specific groups. Any products that are associated to any of these group names will be included. If passing multiple values you can either use the array syntax or separate each entry with a comma.                |
| DEFLANG       | string                           | ❌        | Controls the default Language the Locator/Widget will load with. <br/><br/>By Default Locators and Widgets will use the first Language specified during setup.                                                                                                                                     |
| DEFCTRY       | string                           | ❌        | Controls the default Country the Locator/Widget will load with. <br/><br/>By Default Locators and Widgets will use the first Country specified during setup.                                                                                                                                       |

### Locator Specific

| Property Name | Type                             | Required | Description                                                                                                                                                                                                                                                                                                                           |
|---------------|----------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| locatorType   | DestiniLocatorType &#124; string | ✅        | Specifies which type of locator this should be attempting to load as. Your type of locator can be found on the dashboard or inside your installation instructions.<br/><br/>For compatability purposes this property will accept any string but it is highly recommend to always use the `DestiniLocatorType` type for this property. |

### Widget Specific

While the `APO` and `APOG` properties are not directly required you will need to specify at least one of them for the
widget to function properly. See the [Shared Configuration](#Shared) section for more information about these
properties.

| Property Name        | Type    | Required | Description                                                                                                                                                                                                                                                                                                                                           |
|----------------------|---------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| destini-header-name  | string  | ❌        | Replaces the widget's header text value.<br/><br/>By default the header text uses the name of the first entry inside the `APO` or `APOG` property                                                                                                                                                                                                     |
| destini-header-image | string  | ❌        | Replaces the widget's header image<br/><br/>By default the header image uses the image for the first entry inside the `APO` or `APOG` property.                                                                                                                                                                                                       |
| append-to-body       | boolean | ❌        | When true a new container div will be appended directly to the `body` tag and the Widget will be attached to this div as a shadow container.<br/><br/>This is mainly used to fix z-index issues caused by [Stacking Context](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context) problems. |