# @r2u/react-ar-components

> React components for Augmented Reality on the web.

Latest version **5.4.16** (published 2024-04-24) · SEE LICENSE IN LICENSE.md license · 0 weekly downloads

## Install

```sh
npm install @r2u/react-ar-components
pnpm add @r2u/react-ar-components
yarn add @r2u/react-ar-components
bun add @r2u/react-ar-components
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.4.16 |
| Published | 2024-04-24 |
| First published | 2020-10-16 |
| Weekly downloads | 0 |
| License | SEE LICENSE IN LICENSE.md |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 10 |
| Unpacked size | 1.2 MB |
| Known vulnerabilities | 0 (+4 in 1 direct dependencies) |
| Install scripts | no |
| Maintainers | joseborinr2u, aviggiano |

## Links

- npm: https://www.npmjs.com/package/@r2u/react-ar-components
- Repository: https://github.com/r2u-io/react-ar-components
- npm.io page: https://npm.io/package/@r2u/react-ar-components

## Dependencies (10)

- [react](https://npm.io/package/react.md) ^17.0.2
- [three](https://npm.io/package/three.md) 0.131.2
- [i18next](https://npm.io/package/i18next.md) ^20.2.1
- [react-dom](https://npm.io/package/react-dom.md) ^17.0.2
- [typescript](https://npm.io/package/typescript.md) ^4.3.5
- [react-i18next](https://npm.io/package/react-i18next.md) ^11.8.13
- [styled-components](https://npm.io/package/styled-components.md) ^5.3.0
- [i18next-http-backend](https://npm.io/package/i18next-http-backend.md) ^1.2.1
- [i18next-chained-backend](https://npm.io/package/i18next-chained-backend.md) ^2.1.0
- [i18next-localstorage-backend](https://npm.io/package/i18next-localstorage-backend.md) ^3.1.2

## Recent versions

- 5.4.16 (latest) — 2024-04-24
- 5.4.15 — 2022-12-19
- 5.4.14 — 2022-08-22
- 5.4.13 — 2022-04-28
- 5.4.12 — 2022-03-11
- 5.4.11 — 2022-03-03
- 5.4.10 — 2021-12-14
- 5.4.9 — 2021-12-08
- 5.4.8 — 2021-11-03
- 5.4.7 — 2021-10-29
- 5.4.6 — 2021-10-29
- 5.4.5 — 2021-10-28
- 5.4.4 — 2021-10-07
- 5.4.3 — 2021-09-24
- 5.4.2 — 2021-09-23
- … 51 more at https://npm.io/package/@r2u/react-ar-components/versions

## README

# React AR Components

React components for Augmented Reality on the web.

### Components

- ModelViewer: used to interact with a 3D model on the browser (desktop)
- WebXROverlay: DOM overlay used during a WebXR session (Chrome browser on mobile)

### Methods

- activateAR: tries to open a GLB model on SceneViewer or a USDZ model on quicklook
- activateWebXR: tries to open a GLB model using WebXR, having `activateAR` as a fallback


##### ModelViewer

**Attention:** This component needs the importing of `@google/model-viewer`. We suggest it by adding the script to the page HTML, but it's also possible to add via NPM. Please refer to the [model-viewer documentation](https://modelviewer.dev)

| param                         | description                                                                | default           |
| ----------------------------- | -------------------------------------------------------------------------- | ----------------- |
| `model-viewer default params` | Please refer to [model-viewer documentation](https://modelviewer.dev/docs) | `''`              |
| `ref`\*                       | React RefObject to get/set properties of ModelViewer                       | `undefined`       |
| `className`                   | React ClassName, same as HTML class                                        | `undefined`       |
| `style`                       | object containing custom CSS classes to customize this component           | `undefined`       |
| `children`                    | React component to nest inside model-viewer                                | `undefined`       |
| `componentDidMount`           | function to handle mount event                                             | `() => undefined` |
| `onClick`                     | function to handle click event                                             | `() => undefined` |
| `pan`                         | determines if the model will have pan interaction                          | `true`            |

**\*:** Prop required to make this wrapper work. Can be passed as follows:

```tsx
<ModelViewer ref={React.createRef()} {...props} />
```

##### activateAR

| param              | description                                  | type                     | default           | App         |
| ------------------ | -------------------------------------------- | ------------------------ | ----------------- | ----------- |
| `glb`              | url of the GLB file for Android devices      | `string`                 | `''`              | SceneViewer |
| `usdz`             | url of the USDZ file for iOS devices         | `string`                 | `''`              | QuickLook   |
| `title`            | Display title of object on model card        | `string`                 | `undefined`       | SceneViewer |
| `shareText`        | String to display when sharing AR experience | `string`                 | `undefined`       | Both        |
| `sound`            | URL to play as sound when model is placed    | `string`                 | `undefined`       | SceneViewer |
| `link`             | Link to show on model card                   | `string`                 | `undefined`       | SceneViewer |
| `scale`            | determines if model allows rescale           | `'fixed' \| 'resizable'` | `'fixed'`         | Both        |
| `placement`        | determines the plane to render the model     | `'floor' \| 'wall'`      | `floor`           | SceneViewer |
| `disableOcclusion` | SceneViewer object blending disabling        | `boolean`                | `false`           | SceneViewer |
| `hashFallback`     | New window.location.hash when AR cannot load | `string`                 | `#no-ar-fallback` | SceneViewer |

##### activateWebXR

| param              | description                                  | type                     | default           |
| ------------------ | -------------------------------------------- | ------------------------ | ----------------- |
| `model.glb`        | Url of the model's GLB file                | `string` | `undefined` |
| `model.name`       | Display title of object on model card      | `string` | `undefined` |
| `model.description`| Display text of object on model card       | `string` | `''` |
| `model.url`        | Link to show on model card | `string`                 | `''` |
| `model.placement`  | Determines plane on which the model will be rendered  | `'floor' \| 'wall'` | `undefined` |
| `model.resizable`  | Determines if model allows rescale                    | `boolean`| `undefined` |
| `beforeClose`      | Function called before ending the experience\*        | `(container: HTMLElement) => void` | `defaultBeforeClose` |
| `callToAction`     | Enable CTA on AR experience                           | `CallToAction` | `undefined` |

**\*:**  If provided, `beforeClose` function MUST eventually dispatch the event `r2u-webxr-close` for the WebXR session to end properly.

### Examples

##### activateAR

```tsx
import React, { createRef } from 'react'
import ReactDOM from 'react-dom'

import '@google/model-viewer'

import { ModelViewer, activateAR } from '@r2u/react-ar-components'
import type { ModelViewerElement } from '@r2u/react-ar-components'

import style from './style.module.css'

const App: React.FC = () => {
  const usdz = 'http://localhost:8080/mesh_01000.usdz'
  const glb = 'http://localhost:8080/mesh_01000.glb'
  const imageUrl = 'https://via.placeholder.com/150'
  const viewerRef = createRef<ModelViewerElement>()

  return (
    <div>
      <div>
        <h1>AR</h1>
        <button type="button" onClick={() => activateAR({ glb, usdz })}>
          View in 3D
        </button>
      </div>
      <div>
        <h1>ModelViewer</h1>
        <ModelViewer
          ref={viewerRef}
          src={glb}
          alt="3D model"
          style={style}
          poster={imageUrl}
        />
      </div>
    </div>
  )
}

ReactDOM.render(<App />, document.getElementById('root'))
```

##### activateWebXR

```tsx
import React from 'react'

import { activateWebXR } from '@r2u/react-ar-components'


const App: React.FC = () => {

  const model = {
    resizable: true,
    name: 'Chair',
    description: 'Comfy chair',
    glb:
      'http://localhost:8080/mesh_01000.glb',
    url: 'https://google.com',
    placement: 'floor',
  }

  return (
    <div>
      <h1>WebXR</h1>
      <button type="button" onClick={() => activateWebXR({ model })}>
        Floor
      </button>
    </div>
  )
}

ReactDOM.render(<App />, document.getElementById('root'))
```

## Testing

```shell
make start
```

- Access `http://localhost:8080`
- Or expose local port if testing on another device or on mobile
  - Eg: `npx localtunnel --port 8080`
  - Access exposed link
- Test [banner.html](http://127.0.0.1:8111/banner.html?params=%257B%2522name%2522%253A%2522POLTRONA%2520LUIS%2520XV%2520CAPITON%25C3%258A%2520-%2520WOOD%2520PRIME%252038005%255Cn%2522%252C%2522price%2522%253A%2522R%2524%25201.297%252C00%2522%252C%2522title%2522%253A%2522POLTRONA%2520LUIS%2520XV%2520CAPITON%25C3%258A%2520-%2520WOOD%2520PRIME%252038005%255Cn%2522%252C%2522text%2522%253A%2522Adicionar%2520ao%2520carrinho%2522%257D)

## Analyze bundle size

### React App build

```shell
yarn install
yarn build:app --analyze
```

Visit http://localhost:8888

### SDK build

```shell
yarn install
yarn build:sdk --analyze
```

Visit http://localhost:8888

---
_Source: https://npm.io/package/@r2u/react-ar-components · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
