# Box UI Elements: prebuilt React components for browsing Box content

> Box UI Elements are pre-built components that bring the main Box web application's file browsing, upload, preview and selection into your own application, shipped as React components and as framework-agnostic JavaScript libraries. The licence is the Box Software License Agreement rather than an open source licence, and the build runs on webpack with SCSS.

**box/box-ui-elements** — React Components for Box's Design System and Pluggable Components

- Repository: https://github.com/box/box-ui-elements
- Website: https://developer.box.com/box-ui-elements
- Stars: 551 · Forks: 351
- Language: TypeScript
- License: NOASSERTION
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/box-box-ui-elements

## Six components that cover the file workflows

Box UI Elements are pre-built UI components that allow developers to add features of the main Box web application into their own applications, and the intent is to use them to navigate through, upload, preview and select content stored on Box. They are available as React components and as framework-agnostic JavaScript libraries, so the same set of elements works in a React codebase or in a project that would rather not pull in a framework. The element list is short enough to enumerate and each has its own README under src/elements. ContentExplorer is the main file browser. ContentOpenWith handles the open-with flow. ContentPicker is the selection dialog, which is the component most applications want since it is the piece a user sees when they attach a file to a record. ContentPreview renders a file, and ContentSidebar is a panel version of browsing. ContentUploader handles uploads. The README also separates out two topics that are not elements, authentication and internationalisation, each with its own documentation section, which tells you they are handled at the library level rather than per component. A live demo is published, with the caveat that the demo page has limited functionality.

## Peer dependencies are a manual step you have to plan for

Installation is one package manager command, either yarn add box-ui-elements or npm install box-ui-elements, and then the README adds the part that surprises people. To prevent library duplication, the UI Elements require certain peer dependencies to be installed manually, and the list of required peer dependencies is in package.json. The reason is stated directly, since these libraries are large enough that shipping two copies in a bundle is wasteful, and the fix is to have the application own the shared dependencies rather than having each element carry its own. The package metadata backs up the scale of that, with the element keywords listing explorer, picker, preview, sharing, sidebar and uploader variants, and the main entry point at es/index.js with a separate types entry at es/types.d.ts. The version in package.json is 0.0.0-semantically-released, which is the placeholder that tells you the real version comes from the release tooling rather than from the manifest, and the npm badges show both a latest and a beta channel. The engines field requires Node 20 or newer and yarn 1.10.0 or newer, and the repository carries a .nvmrc alongside a .yarnrc, so the toolchain is pinned for contributors even though consumers get prebuilt packages.

## What the elements actually are, and where they stop

The word elements is Box's name for embeddable pieces of its own web application, and understanding that changes how you evaluate the library. These are not generic file browser components that happen to talk to a Box API, they are the same components Box uses in its own interface, which means they carry Box's own interaction conventions, its design language and its assumptions about what a user is doing. That is the appeal for a developer building a Box integration, since a picker that behaves like the Box web app needs no explanation to the user, and the cost for a developer who wants a neutral file browser, since these components are opinionated about presentation and the design system. The scope of what they cover is also fixed and stated in the README, navigate, upload, preview and select. There is no general folder management, no sharing administration and no permission editing in the element list, so an application that needs those has to reach for the API directly alongside the elements. The application-facing names also give a hint at where each one belongs, with ContentPicker for a modal selection flow, ContentOpenWith for the open-with action, ContentSidebar for a persistent side panel and ContentExplorer for a full page of browsing.

## Code splitting is only available for some elements

The README marks two elements with an asterisk, and the note explains that these components utilize code splitting, with a link to the code splitting section. The two marked are ContentPreview and ContentSidebar, and the mechanism is webpack. Code splitting is currently supported for some UI Elements, and to use an element with code splitting you need to set it up in webpack. This is a practical constraint rather than a caveat, because the two heaviest elements are the ones that can be split out, and an application that only needs a picker does not want to ship a preview and a sidebar into its bundle. The keybind of the feature is that it is opt-in at the bundler level, so a team that does not configure webpack for it gets the whole library, and a team that does gets a smaller initial payload for the elements that support it. The framework-agnostic distribution of the same components is the escape hatch for projects that are not on webpack at all.

## SCSS comes along with each element, which your build has to handle

The stylesheets are part of the package rather than a separate design system you import. Box UI Elements use SCSS stylesheets, each of the Elements includes their corresponding SCSS stylesheet to render properly, and once you import an Element within your React app the corresponding stylesheet will automatically get included. The catch is that your build has to be able to handle it, so you will need to setup webpack to handle .scss files by using the sass-loader and css-loader, which directs webpack to properly include the SCSS files in your final CSS output. A sample configuration is shown in the demo application under the rules section. The upshot is that adding an element to a project is not only a JavaScript dependency change, it is a bundler configuration change, and that is the part of the integration that catches teams out when their build tooling is not webpack. The alternative is the framework-agnostic library, where the same components are shipped without the React wrapper, and the styling question becomes a separate integration concern.

## How the project is built and released

The repository layout shows a mature front end setup. The build scripts in package.json drive webpack through scripts/webpack.config.js with a development and a production variant, and the CI build sets a language and an entry point explicitly, with LANGUAGE and ENTRY variables and a REACT flag, which tells you the same source tree produces several different bundles, one per element, per language and per integration style. The i18n/ directory at the top level holds the translations, and the flow/ and flow-typed/ directories show that the codebase still carries Flow type definitions alongside the TypeScript configuration, with a .flowconfig at the root. Testing is covered from both ends, with a cypress.config.ts for browser-level tests, a .storybook/ directory for component development, a chromatic.config.json for visual regression, a test/ directory, and a .circleci/ directory for continuous integration. Formatting and linting are handled by Prettier, with a .prettierrc.js, plus eslint, stylelint with its own config and ignore file, and a commitlint.config.js for commit message rules. Releases go through semantic-release, and the recent tags are v28.0.0-beta.12, beta.11 and beta.10 in mid-October 2026, with the last push to the repository on 2026-10-20. Mergify is present as a .mergify.yml, and CODEOWNERS is checked in.

## The licence is the deciding constraint

This is a Box Software License Agreement, not an open source licence, and the README is explicit about it. The copyright runs from 2016 to the present, and the licence is the Box Software License Agreement v.20170516, with the terms available at a developer.box.com page. The notice is the standard form, that the file may not be used except in compliance with the licence, that a copy is obtained at that URL, and that unless required by applicable law or agreed to in writing the software is distributed on an as is basis, without warranties, and the licence governs specific language permissions. The practical effect is that the code is readable and you can use the elements inside a Box application, but the permissions are granted by Box under terms you have to read rather than under a permissive open source licence. The repository also carries a THIRD_PARTY_LICENSES file for the components it pulls in. If your requirement is an open source component set that you can vendor, audit and redistribute freely, that is a different evaluation from whether the elements work, and the Box licence is the reason.

## Conclusion

Adopt Box UI Elements if your application needs to let users browse, upload, preview or pick files from Box and you want the same components Box uses in its own web application rather than building a file browser yourself. Skip it if you need an open source licence, since the code is under the Box Software License Agreement and not an OSI-approved licence. Verify first which peer dependencies your build must install manually, whether the element you want supports code splitting since only some do, and that your webpack setup handles the SCSS stylesheets each element pulls in.

## FAQ

### What are Box UI Elements and which ones are there?

They are pre-built UI components that let you add features of the Box web application into your own application, for navigating, uploading, previewing and selecting Box content, available as React components and as framework-agnostic JavaScript libraries. The elements are ContentExplorer, ContentOpenWith, ContentPicker, ContentPreview, ContentSidebar and ContentUploader, with authentication and internationalisation documented separately.

### How do I install Box UI Elements and what do I have to do besides?

Run yarn add box-ui-elements or npm install box-ui-elements. You also have to install certain peer dependencies manually to prevent library duplication, and the list of required peer dependencies is in package.json. The elements also ship SCSS stylesheets, so your webpack setup has to handle .scss files with the sass-loader and css-loader.

### Which Box UI Elements support code splitting?

Code splitting is currently supported for some UI Elements and needs to be set up in webpack. The two marked in the README as using it are ContentPreview and ContentSidebar, which is where the size argument matters most for an application that only needs a picker.

## Sources

- [box/box-ui-elements on GitHub](https://github.com/box/box-ui-elements)
- [Issues](https://github.com/box/box-ui-elements/issues)
- [Project website](https://developer.box.com/box-ui-elements)
- [README](https://github.com/box/box-ui-elements/blob/master/README.md)
- [Releases](https://github.com/box/box-ui-elements/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/box-box-ui-elements