The DICOM Viewer Gutenberg block is the recommended way to add medical image viewers to your pages and posts.
Inserting the Block
- Edit or create a post or page in the WordPress block editor.
- Click the + button to add a new block.
- Search for DICOM Viewer or scroll to find it.
- Click the DICOM Viewer block to insert it.
The block is inserted into your page as a placeholder. The actual viewer renders on the frontend.
Selecting a File
- With the block inserted, click Select File in the block settings panel (on the right).
- A media picker dialog opens — select a
.dcmfile or.ziparchive from your media library. - If the file isn’t in your library yet, click Upload Files to add it.
- Once selected, the block shows the file name and a preview will appear on the frontend.
Block Settings Panel
When the block is selected, the right sidebar shows several setting groups:
| Group | Purpose |
|---|---|
| File Selection | Choose which DICOM file or ZIP to display |
| Display Settings | Height, width, series display style |
| Viewer Controls | Show/hide info button, download button |
| Anonymization | Tag redaction level |
| Layout & Grid | Multi-series layout, grid columns, reference lines |
| Viewport Defaults | Pre-set zoom, pan, window/level, series on load |
All settings are optional — unset values inherit the global defaults from DICOM Viewer.
Alignment
The block supports the wide and full alignment options (available via the alignment control in the block toolbar).
Next Steps
See Block Settings for a complete reference of all configurable block attributes.
Block Settings
This page documents all attributes available in the DICOM Viewer Gutenberg block (dicom-viewer/viewer).
File Selection
| Attribute | Type | Default | Description |
|---|---|---|---|
attachmentId |
number | 0 |
WordPress media library attachment ID of the DICOM file or ZIP |
fileUrl |
string | "" |
Direct URL to a DICOM file (used when attachment ID is not set) |
Note: Provide either attachmentId or fileUrl, not both. attachmentId is preferred because it integrates with WordPress’s media library and permissions.
Display Settings
| Attribute | Type | Default | Description |
|---|---|---|---|
height |
string | "" |
CSS height of the viewer (e.g., 480px, 60vh). Empty = use global default from settings |
seriesDisplay |
string | "" |
How series are displayed: auto, pills, dropdown, none, or empty to inherit global default |
seriesAutoThreshold |
number | 0 |
When seriesDisplay is auto, threshold for switching pills to dropdown (0 = use global default) |
Viewer Controls
| Attribute | Type | Default | Description |
|---|---|---|---|
showInfo |
string | "" |
Show the Info button: "yes", "no", or "" (inherit global). Warning: Info overlay may display PHI. |
showDownload |
string | "" |
Show download link (not yet configurable per-block; follows global General Settings) |
Note: Boolean attributes use string values ("yes" / "no") rather than true/false because an empty string is needed to represent "inherit global default".
Anonymization
| Attribute | Type | Default | Description |
|---|---|---|---|
anonLevel |
string | "" |
Tag redaction level: off, basic, standard, strict, or "" (inherit global default) |
See Anonymization Settings for details on each level.
Layout & Grid
| Attribute | Type | Default | Description |
|---|---|---|---|
layout |
string | "" |
Layout mode: auto, single, grid, or "" (inherit global default) |
gridCols |
number | 0 |
Grid columns (1–4). 0 = use global default. Only applies when layout is grid. |
gridMinSeries |
number | 0 |
Series threshold for auto-grid activation (0 = use global default). Only applies when layout is auto. |
refLines |
string | "" |
Show reference lines in grid: "yes", "no", or "" (inherit global default) |
See Grid Layout for details.
Single-Pane Viewport Defaults
These attributes preset the viewer’s zoom, pan, and window/level when the page loads. They only apply to the single-pane view (not grid layout).
| Attribute | Type | Default | Description |
|---|---|---|---|
defaultSeries |
number | 0 |
Zero-based series index to display on load |
defaultSlide |
number | 0 |
Zero-based slice index within the series |
defaultZoom |
number | 0 |
Zoom factor (1.0 = 100%, 2.0 = 200%, etc.) |
defaultPanX |
number | 0 |
Horizontal pan offset in pixels |
defaultPanY |
number | 0 |
Vertical pan offset in pixels |
Multi-Pane Viewport Defaults
These attributes preset the state of each pane in grid layout. Values are comma-separated (one per pane).
| Attribute | Type | Default | Description |
|---|---|---|---|
defaultPanes |
number | 0 |
Number of grid panes to open initially |
defaultSlides |
string | "" |
Comma-separated slice indices (e.g., 0,5,10 for three panes) |
defaultZooms |
string | "" |
Comma-separated zoom factors |
defaultPanXs |
string | "" |
Comma-separated horizontal pan offsets |
defaultPanYs |
string | "" |
Comma-separated vertical pan offsets |
defaultPaneSeries |
string | "" |
Comma-separated series indices for each pane |
Example: To open 3 panes showing slices 0, 5, and 10 with zoom 1.5x each:
defaultPanes: 3
defaultSlides: "0,5,10"
defaultZooms: "1.5,1.5,1.5"
defaultPanXs: "0,0,0"
defaultPanYs: "0,0,0"
Block Supports
- Alignment:
wideandfullare supported - HTML: HTML editing is disabled for this block
Inheritance & Defaults
All unset (empty string or 0) attributes inherit from the global settings under DICOM Viewer. This makes it easy to set site-wide defaults and override only on specific blocks where needed.
To check what the global defaults are, visit the appropriate Admin Settings tab.
Next Steps
See Shortcode Reference for equivalent shortcode attributes.