Plugin Page

DICOM — WP Medical Image Viewer

Shortcode

The [dicom_viewer] shortcode is an alternative to the Gutenberg block for embedding DICOM viewers. It’s useful if you’re using the classic editor or writing custom templates.

Basic Usage

The simplest way to add a viewer is to provide a file ID from your media library:

[dicom_viewer id="123"]

Replace 123 with your file’s WordPress attachment ID (find this in Media > Library).

Or provide a direct file URL:

[dicom_viewer url="https://example.com/path/to/file.dcm"]

Using the Classic Editor

If you’re using the classic editor instead of Gutenberg, the DICOM Viewer adds a toolbar button. Click the DICOM Viewer icon in the editor toolbar to insert the shortcode with a file selector dialog.

Shortcode Attributes

All attributes are optional except one of id or url. Full details are in the Shortcode Reference.

Common attributes:

[dicom_viewer
  id="123"
  height="600px"
  show_info="false"
  layout="auto"
  grid_min_series="3"
  anon_level="standard"
]

Setting Viewport Defaults

You can pre-set the viewer’s starting zoom and position:

[dicom_viewer
  id="123"
  default_zoom="2.0"
  default_series="1"
  default_slide="15"
]

For multi-series with grid layout, you can set per-pane values:

[dicom_viewer
  id="123"
  layout="grid"
  default_slides="0,5,10"
  default_zooms="1.5,1.5,1.5"
  default_wcs="40,40,40"
  default_wws="400,400,400"
]

Shortcode Reference

This page lists all options you can use in the [dicom_viewer] shortcode to customize how the viewer displays.

Choosing Your File

You must provide either a file ID from your media library OR a direct URL:

Attribute	Type	Default	Description
`id`	integer	`0`	WordPress media library attachment ID
`url`	string	`""`	Direct URL to a `.dcm` or `.zip` file

Note: Use id when the file is in your WordPress media library (preferred). Use url for files hosted externally.

Sizing

Option	Values	What it does
`height`	e.g., `480px`, `600px`, `70vh`	How tall the viewer should be
`width`	e.g., `100%`, `800px`	How wide the viewer should be

Buttons & Controls

Option	Values	What it does
`show_download`	`true` or `false`	Show/hide the download button
`show_info`	`true` or `false`	Show/hide the info button (displays image metadata)
`show_pan_control`	`true` or `false`	Show/hide the Pan tool
`show_zoom_control`	`true` or `false`	Show/hide the Zoom tool and zoom buttons
`show_wl_control`	`true` or `false`	Show/hide the window/level controls
`show_nav_buttons`	`true` or `false`	Show/hide the next / previous slice buttons
`show_slider`	`true` or `false`	Show/hide the slice slider

Multiple Series

Option	Values	What it does
`layout`	`auto`, `single`, `grid`	Single image or side-by-side grid
`grid_cols`	`1`, `2`, `3`, `4`	How many columns in grid view
`grid_min_series`	`2` to `10`	Minimum number of series required before `layout="auto"` switches to grid
`ref_lines`	`true`, `false`	Show/hide reference lines connecting panes
`show_series_selector`	`true` or `false`	Show/hide the series selector UI
`show_pane_selector`	`true` or `false`	Show/hide the pane count selector in grid mode
`series_display`	legacy compatibility	Older content may still use `none` to hide the selector

Hiding Sensitive Information

Option	Values	What it does
`anon_level`	`off`, `basic`, `standard`, `strict`	Hide patient info in the metadata display

off = show all information
basic = hide patient name and ID
standard = hide patient info + hospital details
strict = hide almost everything except the image

Default Viewport (Advanced)

If you want the viewer to open at a specific series, slice, zoom level, or window/level, you can set:

Option	What it does
`default_series`	Starting series index (0 = first series, 1 = second, etc.)
`default_slide`	Starting slice index within the series
`default_zoom`	Starting zoom level (1.0 = normal, 2.0 = 2x zoom, 0.5 = zoomed out)
`default_pan_x`	Starting horizontal pan offset
`default_pan_y`	Starting vertical pan offset
`default_wc`	Starting window center
`default_ww`	Starting window width

Example:

[dicom_viewer id="42" default_series="1" default_slide="12" default_zoom="1.5"]

For grid layout with multiple panes, you can set different values for each pane:

[dicom_viewer
  id="42"
  layout="grid"
  default_panes="3"
  default_slides="0,5,10"
  default_zooms="1.5,1.5,2.0"
  default_wcs="40,40,60"
  default_wws="400,400,250"
  default_pane_series="0,0,1"
]

Additional grid viewport options:

Option	What it does
`default_panes`	Number of panes to show initially
`default_slides`	Comma-separated slice indices per pane
`default_zooms`	Comma-separated zoom levels per pane
`default_pan_xs`	Comma-separated horizontal pan offsets per pane
`default_pan_ys`	Comma-separated vertical pan offsets per pane
`default_wcs`	Comma-separated window center values per pane
`default_wws`	Comma-separated window width values per pane
`default_pane_series`	Comma-separated series indices per pane

Using Global Settings

If you don’t specify an option in the shortcode, it uses the default from DICOM Viewer.

For example, if your global default height is 480px, you don’t need to add height="480px" to every shortcode.

True/False Values

For options that take true or false, you can write:

true, 1, or yes for on
false, 0, or no for off

Example: show_info="true" or show_download="1"

Common Examples

Just show the image:

[dicom_viewer id="123"]

Make it taller:

[dicom_viewer id="123" height="800px"]

Hide patient info:

[dicom_viewer id="123" anon_level="strict"]

Show multiple images side-by-side:

[dicom_viewer id="123" layout="grid" grid_cols="2"]

Start zoomed in:

[dicom_viewer id="123" default_zoom="2.0"]

Don’t allow downloads:

[dicom_viewer id="123" show_download="false"]