Table of Contents

Create a custom interface

If you find that our out-of-the-box Editor does not have the functionality you need, you can build your own custom labeling interface (explore some of our open-source custom editors here). We also offer a JavaScript SDK you can use to programmatically fetch assets and submit labels.

With a custom editor, you can label:

  • point clouds
  • medical DICOM imagery
  • multiple assets at once

To set up a simple custom labeling interface, follow these steps

Step 1: Run a localhost server

  1. Set up your custom interface locally. You can use this Hello world script as an example.
  2. Start the localhost server in a directory containing your custom interface frontend files. For example, run the server inside custom-interfaces/hello-world to run the Hello world custom interface locally.
python -m SimpleHTTPServer
  1. Open your browser and navigate to the localhost endpoint provided by the server.
  2. Customize the labeling frontend by making changes to index.html.
  3. Restart the server and refresh the browser to see the updates.

Step 2: Install your custom editor in Labelbox

Upload your index.html file to a cloud service that exposes a URL for Labelbox to fetch the file. Then, install your custom editor in Labelbox by pointing to the hosted version of it. If you don’t have a hosting service on-hand, follow these steps to launch your custom editor with Now.

  1. Create an account at Zeit.
  2. Download and install Now.
  3. With Now installed, navigate to the directory with your custom editor (where your index.html is located) and launch Now in your terminal by typing now. The Now service will provide a link to your hosted labeling interface file.
  4. Within the “Labeling Interface” menu of the Settings tab of your Labelbox project, choose “Custom” and paste the link in the “URL to labeling frontend” field.

Step 3: Create the import file

Include the following information when you import you data for labeling.




Text that will appear when the labeler opens the asset(s) in the labeling interface.


Can be used to upload a larger reference image to help labelers.


User generated identifier used to index the asset in user’s system.

imageUrl (REQUIRED)

HTTPS URL to an image file.

Sample JSON import
"instructions": "<p>Which cars do you like the most?</p>",
"data": [
"externalId": "ab65d5e99w12",
"imageUrl": ""
"externalId": "abadsf99w13",
"imageUrl": ""

Fetch and submit via the API

Here is an example end-to-end script for a minimal custom interface. See our API reference for more.

// Attach the Labelbox client-side API
<script src=""></script>
<div id="form"></div>


// Fetch an asset to label then submit the label
function label(label){
Labelbox.setLabelForAsset(label).then(() => {

// Draw the next asset
Labelbox.currentAsset().subscribe((asset) => {
if (asset){

//Display the labeling interface
function drawItem(dataToLabel){
const labelForm = `
<img src="${dataToLabel}" style="width: 300px;"></img>
<div style="display: flex;">
<button onclick="label('bad')">Bad Quality</button>
<button onclick="label('good')">Good Quality</button>
document.querySelector('#form').innerHTML = labelForm;


Sample custom editor interfaces

Was this page helpful?

labeling-api.js API reference