UI Elements can be used either by downloading the Javascript libraries
directly from the Box CDN or by installing our NPM package. All UI
Elements require their corresponding CSS stylesheet to render properly.
Prerequisites
To use Box UI Elements, you need the following Node and React versions:
- Node version:
>=18.18.2 <22.11.0
- React version
>=18.0.0 <=19.0.0
The available versions of UI elements are listed in the manual installation section.
Migration to React 19
For existing projects based on React 18 or below, check the React 19 migration guide.
Update react-tether in your package.json to >= v3.0.3 to avoid compatibility issues.
box-ui-elements package with npm or yarn:
npm install box-ui-elements --legacy-peer-deps
yarn add box-ui-elements
package.json file:
"box-ui-elements": "^26.0.0"
NPM installation
Use this when you are building a React based app and would like to import the
components directly into your app at build time.
Note The --legacy-peer-deps flag is necessary when installing UI elements with npm due to library dependencies.
npm install box-ui-elements --legacy-peer-deps
yarn add box-ui-elements
Learn more on the NPM website
Content Preview
Use the Content Preview SDK if you need a specific
version of the preview library. Otherwise,
use Content Preview UI Element wrapper.Manual installation
All the UI elements are also available directly from the Box CDN.
Use these links to either download the elements code to your application’s
code, or embed them straight into your page from the CDN.
<!DOCTYPE html>
<html lang="en-US">
<head>
<!-- Latest version of the explorer css for your locale -->
<link
rel="stylesheet"
href="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/explorer.css"
/>
</head>
<body>
<!-- Latest version of the explorer js for your locale -->
<script src="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/explorer.js"></script>
...
</body>
</html>
<!DOCTYPE html>
<html lang="en-US">
<head>
<meta charset="utf-8" />
<title>Box Content Preview Demo</title>
<!-- Latest version of Box Content Preview for en-US locale -->
<script src="https://cdn01.boxcdn.net/platform/preview/{VERSION}/en-US/preview.js"></script>
<link
rel="stylesheet"
href="https://cdn01.boxcdn.net/platform/preview/{VERSION}/en-US/preview.css"
/>
</head>
<body>
<div class="preview-container" style="height:400px; width:100%;"></div>
<script>
var preview = new Box.Preview();
preview.show("93392244621", "EqFyi1Yq1tD9mxY8F38sxDfp73pFd7FP", {
container: ".preview-container",
showDownload: true,
});
</script>
</body>
</html>
Versions
Most of the UI elements have 2 distinct versions.
- A standard
*.js file (e.g. explore.js) that includes React and ReactDOM in the bundle.
- Use this when you are not building a React based app or you don’t want to include the components as part of your app’s build process.
- It includes React and ReactDOM libraries.
- The file size of this asset will be larger than the one below.
- A smaller
*.no.react.js file (e.g. explore.no.react.js) that does not get bundled with React and ReactDOM.
- Use this when both React and ReactDOM libraries are already loaded on the application.
- These libraries expect a React and ReactDOM
>= 16.6 and < 18.
Supported Locales
The above asset URLs use en-US. If you want to use another locale, then
replace en-US in the URLs above with any of the following:
en-AU, en-CA, en-GB, da-DK, de-DE, es-ES, fi-FI, fr-CA, fr-FR,
it-IT, ja-JP,, ko-KR, nb-NO, nl-NL, pl-PL, pt-BR, ru-RU,
sv-SE, tr-TR, zh-CN, zh-TW
Self-hosting Content Preview
To serve the Box Content Preview library from your own server, follow these
steps.
1. Download release
Either fork the repository and check out the version you want to serve or
download the specific version as a zip.
- Check out a specific version with
git checkout v3.0.0.
- Download a specific version as a zip from the releases page.
2. Install dependencies
Install the dependencies and build the library with the following command.
yarn install && yarn build:i18n && yarn build:prod
3. Serve files
Self-serve everything except for the dev folder from the /dist folder. You
must not alter the folder structure and third-party needs to be in the same
folder as 3.0.0.
For example, if you self-host using a box-assets directory, these URLs must
be accessible:
https://cdn.YOUR_SITE.com/box-assets/3.0.0/en-US/preview.jshttps://cdn.YOUR_SITE.com/box-assets/third-party/text/2.65.0/papaparse.min.jshttps://cdn.YOUR_SITE.com/box-assets/third-party/model3d/1.12.0/three.min.js
Authentication
In order to initialize any of the UI Elements, an application will need to
provide a valid Access Token.
Learn how to authenticate an application
CORS
To use UI Elements, an application needs to allow the domain the widget is
used on for Cross Origin Resource sharing. See the CORS guide for more
details.
Source Code & Releases
Source code for Box UI Elements is hosted on GitHub. The repository
contains detailed documentation for usage and development. Please file any bugs
you encounter under the “Issues” tab with clear steps to reproduce. This
repository also holds a list of releases.
