Skip to main content
Version: 3.13.0-beta.61 (Latest)

Viewport Scrollbar

The viewport scrollbar customization controls whether OHIF uses:

  • the new progress-based scrollbar (viewportScrollbar.variant: 'progress'), or
  • the legacy range-input scrollbar (viewportScrollbar.variant: 'legacy').

When using 'progress', stack and acquisition-plane volume viewports run in full progress mode (fills/endpoints/loading options apply - see below), while other slice-capable viewports run in minimal mode (indicator only).

Advanced: viewportScrollbar.indicator​

viewportScrollbar.indicator sets the progress indicator’s outer size (totalWidth, totalHeight, border included) and a renderIndicator function. The platform passes React into renderIndicator so the same shape works from plain window.config files (use React.createElement there instead of JSX). If totalWidth, totalHeight, and renderIndicator are not all valid, the default pill indicator is used.

For richer UI, declare the override in an extension getCustomizationModule (or another .tsx module) where you can return real JSX from renderIndicator.

To read layout while drawing the indicator (track size, loading state, isDragging, etc.), use useSmartScrollbarLayoutContext from @ohif/ui-next inside a small React component that you return from renderIndicator (for example return <MyIndicator /> or React.createElement(MyIndicator)). Do not call that hook directly in the renderIndicator function body: that function is not a component render, so hooks would break the rules of React.

viewportScrollbar.variant

IDviewportScrollbar.variant
Description
Controls which scrollbar implementation is rendered. Use progress for ViewportSliceProgressScrollbar and legacy for ViewportImageScrollbar.
progress (default)
legacy
Default Value
progress
Example

window.config = {
  // rest of window config
  customizationService: [
    {
      'viewportScrollbar.variant': {
        $set: 'legacy',
      },
    },
  ],
};

viewportScrollbar.showLoadedEndpoints

IDviewportScrollbar.showLoadedEndpoints
Description
Shows/hides loaded-range endpoint caps in full progress mode (stack or acquisition-plane volume).
Loaded-range endpoint caps
Default Value
true
Example

window.config = {
  // rest of window config
  customizationService: [
    {
      'viewportScrollbar.showLoadedEndpoints': {
        $set: false,
      },
    },
  ],
};

viewportScrollbar.showLoadedFill

IDviewportScrollbar.showLoadedFill
Description
Shows/hides the loaded/cached fill track in full progress mode.
Loaded/cached fill track
Default Value
true
Example

window.config = {
  // rest of window config
  customizationService: [
    {
      'viewportScrollbar.showLoadedFill': {
        $set: false,
      },
    },
  ],
};

viewportScrollbar.showViewedFill

IDviewportScrollbar.showViewedFill
Description
Shows/hides the viewed fill track in full progress mode.
Viewed fill track
Default Value
true
Example

window.config = {
  // rest of window config
  customizationService: [
    {
      'viewportScrollbar.showViewedFill': {
        $set: false,
      },
    },
  ],
};

viewportScrollbar.showLoadingPattern

IDviewportScrollbar.showLoadingPattern
Description
Shows/hides the dotted loading pattern for full progress mode. Minimal mode always disables this pattern.
Dotted loading pattern
Default Value
true
Example

window.config = {
  // rest of window config
  customizationService: [
    {
      'viewportScrollbar.showLoadingPattern': {
        $set: false,
      },
    },
  ],
};

viewportScrollbar.viewedDwellMs

IDviewportScrollbar.viewedDwellMs
Description
Minimum time in milliseconds the current slice must stay on screen before it is marked as viewed in full progress mode. 0 marks immediately.
Default Value
0
Example

window.config = {
  // rest of window config
  customizationService: [
    {
      'viewportScrollbar.viewedDwellMs': {
        $set: 500,
      },
    },
  ],
};

viewportScrollbar.loadedBatchIntervalMs

IDviewportScrollbar.loadedBatchIntervalMs
Description
Coalesces loaded/cached slice state changes into a single UI update at the configured interval in full progress mode. Lower values feel more responsive but trigger more re-renders; higher values reduce render churn but can make progress updates appear delayed. Set to 0 for immediate updates.
Default Value
200
Example

window.config = {
  // rest of window config
  customizationService: [
    {
      'viewportScrollbar.loadedBatchIntervalMs': {
        $set: 100,
      },
    },
  ],
};

viewportScrollbar.indicator

IDviewportScrollbar.indicator
Description
Outer size (totalWidth × totalHeight, border included) and renderIndicator for the progress scrollbar indicator. renderIndicator receives React for config file compatibility. All three properties must be provided or the default pill is used. See Advanced for TSX overrides and useSmartScrollbarLayoutContext.
Default Value
{}
Example

This example sets a 10×10 SVG indicator (muted outer circle, lighter inner circle) via React.createElement, matching totalWidth and totalHeight.


window.config = {
  // rest of window config
  customizationService: [
    {
      'viewportScrollbar.indicator': {
        totalWidth: 10,
        totalHeight: 10,
        renderIndicator: function (React) {
          return React.createElement(
            'svg',
            { width: 10, height: 10, viewBox: '0 0 10 10' },
            React.createElement('circle', {
              cx: 5,
              cy: 5,
              r: 5,
              fill: 'hsl(213 22% 59% / 0.9)',
            }),
            React.createElement('circle', {
              cx: 5,
              cy: 5,
              r: 4,
              fill: 'hsl(0 0% 98% / 0.9)',
            })
          );
        },
      },
    },
  ],
};