The Box DICOM Viewer allows users to store, view and share DICOM files (X-rays, CT scans, Ultrasounds and MRIs) securely in the cloud. The Box DICOM Viewer is an FDA cleared Class II Medical Device for diagnostic viewing. It is a zero-footprint HTML5 viewer and can be embedded into an application in an iFrame or with a Javascript SDK.

If you are a developer and want to embed the Box DICOM Viewer into your application, please email us at for more information.

Current Version

Update to v1.3.0 or higher

If you are using a version of the DICOM Viewer prior to v1.3.0, please upgrade to v1.3.0 or higher.

  • Version: 1.3.5
  • Locale: en-US

Supported Locales

To use a different locale, replace en-US in the JS URL above with any of the following supported locales:

en-AU, en-CA, en-GB, en-US, da-DK, de-DE, es-ES, fi-FI, fr-CA, fr-FR, hu-HU, it-IT, ja-JP, ko-KR, nb-NO, nl-NL, pl-PL, pt-BR, ru-RU, sv-SE, tr-TR, zh-CN, zh-TW

DICOM Viewer iFrame Embed

The Box DICOM Viewer can be embedded in an IFrame, or linked directly. The URL pattern for the Box DICOM Viewer is:

The File ID can be obtained from the API or from the Box web application user interface.

The following options can be provided as query string parameters:

  • accessToken - A Box API access token.
  • sharedName - a global link to a folder.
  • toolbar–Boolean parameter to show or hide the top toolbar. Default is true.
  • overlays–Boolean parameter to show or hide the text overlays. Default is true.
  • worklist–Boolean parameter to show or hide the side worklist. Default is true.

After you have constructed the URL, you can embed it in an IFrame or link to it directly. Here is sample IFrame code:

<iframe width="800" height="600" src="MY URL"allowfullscreen><p>Box DICOM Viewer</p></iframe>

allowfullscreen is Required

The allowfullscreen attribute is required for the Box DICOM Viewer full-screen function to work properly.

DICOM Viewer Javascript SDK


Quickstart Example

<!DOCTYPE html>
<html lang="en">
  <meta charset="utf-8">
  <title>Box DICOM Viewer</title>
  <link rel="stylesheet" href="">
  <script src=""></script>

  <div class="box-dicom-viewer-body"></div>
    box.dicom.createViewer(document.querySelector('.box-dicom-viewer-body'), {
      'accessToken': 'ACCESS_TOKEN_HERE',
      'studies': [{'fileId': 'FILE_ID_HERE'}]

The primary function to create a viewer is box.dicom.createViewer(). The proper definition is:

box.dicom.createViewer(element, config)


  • element–The DOM element to initialize the viewer into. Can be either a string (a DOM element ID) or an Element (a DOM element).
  • config–The configuration object.

The config is a Javascript object with many possible options in the form of properties.

  • accessToken-The access token for the user. Must have access to the ".boxdicom" file AND all of the individual ".dcm" files.
  • studies-An array of studies to load. Each study is an object. Each study object can specify a study by the Box File ID ("fileID": "123456").
  • overlays–Optional overlay configuration details.
  • toolbar–Optional toolbar configuration details.
  • worklist–Optional worklist configuration details.
  • hangingProtocols–Optional hanging protocols to control the layout and display settings of the study.

You can enable / disable overlays using the visible property:

  "accessToken": "asdf",
  "studies": [/* ... */],
  "overlays": {
    "visible": false

You can control which fields are displayed using the fields property:

  "accessToken": "asdf",
  "studies": [/* ... */],
  "overlays": {
    "visible": true,
    "fields": [

You can show / hide the toolbar using the visible property.

  "accessToken": "asdf",
  "studies": [/* ... */],
  "toolbar": {
    "visible": false

You can control which buttons are displayed using the buttons property:

  "accessToken": "asdf",
  "studies": [/* ... */],
  "toolbar": {
  	"visible": true,
		"buttons": [

You can show / hide the worklist using the visible property.

  "accessToken": "asdf",
  "studies": [/* ... */],
 	"worklist": {
  	"visible": false

DICOM Import Javascript SDK

The Box DICOM Import tool intelligently crawls through folders and subfolders to find your DICOM data. It can recognize non-DICOM to avoid uploading unwanted content such as executables. The resulting files are organized by patient and study details.

The Box DICOM Import widget can be embedded in your applications using the JavaScript SDK.

box.dicom.createImportWidget('my-container', {
  'accessToken': 'MY_ACCESS_TOKEN',
  'folderId': 'MY_FOLDER_ID'

Here is an example of how to use the "success" callback:

box.dicom.createImportWidget('my-dicom-import-container', {
  'folderId': '123',
  'accessToken': 'abc','success': function(e) {
    console.log('Patient Name = '+ e.getStudy().getPatientName().getDisplayString());
    console.log('Folder ID= '+ e.getStudy().getFolderId());
    console.log('File ID     = '+ e.getStudy().getFileId());

Available Overlay Fields

box.dicom.core.Tag.AdditionalPatientHistory, box.dicom.core.Tag.BitsAllocated, box.dicom.core.Tag.BitsStored, box.dicom.core.Tag.BluePaletteColorLookupTableData, box.dicom.core.Tag.BluePaletteColorLookupTableDescriptor, box.dicom.core.Tag.BodyPartExamined, box.dicom.core.Tag.Columns, box.dicom.core.Tag.CompensatorPixelSpacing, box.dicom.core.Tag.GreenPaletteColorLookupTableData, box.dicom.core.Tag.GreenPaletteColorLookupTableDescriptor, box.dicom.core.Tag.FrameOfReferenceUID, box.dicom.core.Tag.HighBit, box.dicom.core.Tag.ImageOrientationPatient, box.dicom.core.Tag.ImagePlanePixelSpacing, box.dicom.core.Tag.ImagePositionPatient, box.dicom.core.Tag.ImagerPixelSpacing, box.dicom.core.Tag.InstanceNumber, box.dicom.core.Tag.InstitutionName, box.dicom.core.Tag.Item,
box.dicom.core.Tag.ItemDelimitationItem, box.dicom.core.Tag.ModalitiesInStudy, box.dicom.core.Tag.Modality, box.dicom.core.Tag.NumberOfFrames, box.dicom.core.Tag.OverlayColumns, box.dicom.core.Tag.OverlayData, box.dicom.core.Tag.OverlayRows, box.dicom.core.Tag.PatientAge, box.dicom.core.Tag.PatientBirthDate, box.dicom.core.Tag.PatientName, box.dicom.core.Tag.PatientID, box.dicom.core.Tag.PatientSex, box.dicom.core.Tag.PhotometricInterpretation, box.dicom.core.Tag.PixelData, box.dicom.core.Tag.PixelRepresentation, box.dicom.core.Tag.PixelSpacing, box.dicom.core.Tag.PresentationPixelSpacing, box.dicom.core.Tag.PrinterPixelSpacing, box.dicom.core.Tag.ProtocolName, box.dicom.core.Tag.RedPaletteColorLookupTableData, box.dicom.core.Tag.RedPaletteColorLookupTableDescriptor, box.dicom.core.Tag.ReferringPhysicianName, box.dicom.core.Tag.RescaleIntercept, box.dicom.core.Tag.RescaleSlope, box.dicom.core.Tag.Rows, box.dicom.core.Tag.SequenceDelimitationItem, box.dicom.core.Tag.SeriesDescription, box.dicom.core.Tag.SeriesInstanceUID, box.dicom.core.Tag.SeriesNumber, box.dicom.core.Tag.SOPInstanceUID, box.dicom.core.Tag.SpecificCharacterSet, box.dicom.core.Tag.StudyDate, box.dicom.core.Tag.StudyDescription, box.dicom.core.Tag.StudyInstanceUID, box.dicom.core.Tag.TransferSyntaxUID, box.dicom.core.Tag.WindowCenter, box.dicom.core.Tag.WindowCenterWidthExplanation, box.dicom.core.Tag.WindowWidth

Available Toolbar Options

box.dicom.viewer.Toolbar.Buttons.Logo, box.dicom.viewer.Toolbar.Buttons.Separator, box.dicom.viewer.Toolbar.Buttons.Stack, box.dicom.viewer.Toolbar.Buttons.WindowLevel, box.dicom.viewer.Toolbar.Buttons.Zoom, box.dicom.viewer.Toolbar.Buttons.Pan, box.dicom.viewer.Toolbar.Buttons.ThreeDCursor, box.dicom.viewer.Toolbar.Buttons.Annotate,
box.dicom.viewer.Toolbar.Buttons.Separator, box.dicom.viewer.Toolbar.Buttons.Grid, box.dicom.viewer.Toolbar.Buttons.Overlays, box.dicom.viewer.Toolbar.Buttons.More


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.