3 easy ways to customize the Box UI Elements

Last month, we released the Box UI Elements — a collection of modular Javascript components that you can use to bring parts of the Box UI to your own app and customize it to fit your needs. Already, we’re seeing dozens of apps from businesses of all sizes using the Box UI Elements to easily build user experiences with content.

You can learn more about the Box UI Elements in our announcement post here and check out demos of the UI Elements on Codepen. You can also learn how to use the UI Elements in our developer documentation.

One of the reasons developers use the Box UI elements is to create a Box-like experience in their apps. Not only do the UI Elements help you build apps faster by not having to build your own UI, they also allow you to leverage design and UX best practices that we’ve developed over the years in our own web applications. The principle difference between the UI Elements and other types of embeddable widgets is your ability to customize the elements to fit your use case and brand.

There are effectively three different methods of customizing the UI Elements: optional parameters, token permissions, and good old CSS. In this post, I’ll share three simple ways you can customize the UI Elements. For demonstration purposes, I’ll use the Box Content Explorer UI Element throughout all three examples.

Adding your own logo to the Box UI Elements

One of the most common ways to customize a UI Element is to add your company’s logo to display in the top-left corner of the UI Element. By default, we’ve provided an SVG placeholder for a logo.

Default logo for a Box UI Element

To provide a logo, you’ll need to specify a URL of your company’s logo as a parameter when initializing an instance of a UI Element.

You can also provide the ‘box’ string if you want to use the Box logo:

var FOLDER_ID = ‘31472846046’;
var TOKEN = ‘EqFyi1Yq1tD9mxY8F38sxDfp73pFd7FP’;
var contentExplorer = new Box.ContentExplorer();
contentExplorer.show(FOLDER_ID, TOKEN, {
logoUrl: ‘box’
});

Box logo displayed in a Box UI Element

var FOLDER_ID = ‘31472846046’;
var TOKEN = ‘EqFyi1Yq1tD9mxY8F38sxDfp73pFd7FP’;
var contentExplorer = new Box.ContentExplorer();
contentExplorer.show(FOLDER_ID, TOKEN, {
logoUrl: ‘https://seeklogo.com/images/B/Batman-logo-F8295E46F2-seeklogo.com.png'
});

Custom logo displayed in a Box UI Element

You can play around with the logoUrl option in our CodePen demo.

Automatically show or hide UI controls based on permissions

To initialize a UI Element, you need to supply a few fundamental parameters, including an access token, to the client. With the access token, the client can make API calls directly to Box. Access Tokens are obtained through the authentication process, either using standard 3-legged OAuth 2.0 or OAuth 2.0 with JWT for using Service Accounts and/or App Users. You can find more information about these authentication methods here.

As part of our announcement around UI Elements, we introduced a new mechanism for taking this access token and “exchanging” it for a token with more specific permissions to pass to the client. This helps you avoid passing a fully-scoped access token to the client, where it could create an unnecessary vulnerability in your app. Effectively, you take your access token with all the permissions your app may require and exchange it for a token with only the permission you want the client to have and then give that token to the UI Element to initialize it.

One of the benefits of using the UI Elements over building your own UI is that the UI Elements will automatically show or hide controls based on the access token’s permissions. For example, if you have a token that does not have permissions to share a file (or, create a URL that a user can share), the “Share” button will not display. This type of modification can be enforced either through a simple parameter (canShare) or by exchanging your access token for one that does not have sharing capabilities. The UI Element will automatically adjust.

Box UI Element with sharing permissions enabled

Box UI Element with sharing permissions disabled

Customizing the CSS

UI Elements are designed to work easily out-of-the-box, so you can embed a Box-like user experience in your app with just a few lines of code. That said, there are times where you might want to provide a more integrated user experience, where you leverage the UI Element as a starting place for your UI and your integration with the Box Platform APIs, but the user experience is aligned with the rest of your app. Perhaps you use a certain color or font.

The Box UI Elements can be easily customized using basic CSS commands. By right-clicking on an area of the Element, you can find the name of the CSS class and modify it. We’ll also open up the source code for each of the UI Elements soon, where you’ll be able to fork the complete stylesheet and modify to fit your needs.

Here’s an example of changing the header color using a demo on Codepen:

Customizing the CSS for a Box UI Element

This is obviously a very simple example of what’s possible with custom CSS. You can imagine that with a little CSS magic, you could modify a UI Element to look very different from it’s original state.

We’d love to hear your thoughts and feedback on the Box UI Elements and see the types of customizations you’ve made! Feel free to reach out to us on Twitter or email us at box-ui-elements@box.com. We can’t wait to see what you build!