docs(site): add ui-next component documentation and upgrade Docusaurus (#6102)

This commit is contained in:
Dan Rukas authored and GitHub committed 2026-06-29 12:33:16 -04:00
1 parent 03b180f185
commit ac45a9497f
112 files changed
+9665 -6674

No files matched your search

@@ -118,6 +118,7 @@ window.config = ({ servicesManager } = {}) => {
Here are a list of some options available:
- `customizationService`: An array of customization module references and inline overrides applied at the global scope. This is how deployers enable optional features like the [Appearance & Theming](./ui.md) system and configure UI components without modifying core code. See [Customization Service](../platform/services/customization-service/customizationService.md) for the full syntax reference.
- `disableEditing`: If true, it disables editing in OHIF, hiding edit buttons in segmentation
panel and locking already stored measurements.
- `maxNumberOfWebWorkers`: The maximum number of web workers to use for
+161
View File
@@ -0,0 +1,161 @@
---
sidebar_position: 5
sidebar_label: UI & Appearance
title: UI & Appearance
summary: Overview of OHIF's UI system — the component library, theming and appearance customization, iconography, and the services that drive modals, dialogs, notifications, and viewport layout.
---
# UI & Appearance
OHIF's user interface is built on **ui-next**, a component library purpose-built
for medical imaging workflows. It provides a consistent set of React components,
a token-based theming system, a curated icon set, and a collection of UI services
that manage runtime behavior like modals, notifications, and viewport layout.
This page gives a high-level map of how these pieces fit together and where to
find detailed documentation for each.
## Component Library
The [component library](/components) is the foundation of every panel, toolbar, dialog, and
control in the viewer. Components are organized into three tiers:
- **Simple components** — atomic building blocks like Button, Checkbox, Input,
Label, Slider, and Switch. These are styled with the design system's tokens and
are the smallest interactive units.
- **Compound components** — composed from simple components to handle more
complex interactions: Select, Dialog, DropdownMenu, Tabs, Table, Popover,
Tooltip, Toast, and others. These manage their own state (open/close, selection,
focus) via headless patterns.
- **OHIF-specific components** — built for medical imaging workflows and not
found in general-purpose libraries: AllInOneMenu, CinePlayer, DataRow,
DataTable, Numeric, PanelSection, SmartScrollbar, ToolButton, and
ToolButtonList. These integrate directly with OHIF's services and extension
system.
Every component renders live in the interactive
[Components](/components) section of this documentation site, where you
can see props, variants, and copy usage examples.
## Appearance Dialog
The Appearance dialog is an optional UI that lets end users switch presets,
apply custom CSS overrides, and share themes via URL. It is not enabled by
default, but deployers can
[opt in via configuration](../platform/services/customization-service/appearance-theming.md#enabling-the-theme-module).
See [Appearance & Theming](../platform/services/customization-service/appearance-theming.md)
for the full setup and developer guide.
## Colors & Theming
OHIF uses a **token-based color system** built on CSS custom properties with HSL
values. The base theme (dark mode) is defined in `:root` via Tailwind CSS, and
theme presets override specific tokens by applying a CSS class to `document.body`.
The theming system covers:
- **[Design tokens](/colors-and-theming#color-tokens-and-roles)** — a set of semantic color variables (`--background`,
`--primary`, `--card`, `--border`, etc.) that every component references. Tokens
are defined as HSL triplets and consumed via Tailwind's `hsl(var(...))` pattern.
- **Theme presets** — six built-in themes (three tonal, three neutral) that shift
the entire interface's color palette. Presets are defined as JSON files and
applied via CSS classes. Also see:
[Creating Themes](/colors-and-theming#creating-themes) and
[Adding a Theme Preset](../platform/services/customization-service/appearance-theming.md#adding-a-theme-preset).
- **Accessibility** — foreground tokens are paired with every surface token to
maintain contrast ratios across themes. When adding custom themes,
[test colors to match accessibility standards](/colors-and-theming#accessibility).
Explore the live token swatches and theme picker in the interactive
[Colors & Theming](/colors-and-theming) page, and see
[Appearance & Theming](../platform/services/customization-service/appearance-theming.md)
for the full configuration and developer guide.
## Iconography
OHIF ships a curated set of icons designed specifically for medical imaging interfaces.
Icons are SVG-based, registered via `addIcon()`, and rendered through the `Icons`
component. They follow the same token system as the rest of the UI, so icon colors
respond to the active theme.
Browse the full set with search and click-to-copy in the
[Iconography](/components/icons) page.
## White Labeling
OHIF supports replacing the header logo with custom branding via the
`whiteLabeling` configuration key. This lets you rebrand the viewer without
modifying source code.
Add a `whiteLabeling` entry to your configuration file with a
`createLogoComponentFn` that returns a React element:
```js
window.config = {
/** .. **/
whiteLabeling: {
createLogoComponentFn: function(React) {
return React.createElement(
'a',
{
target: '_self',
rel: 'noopener noreferrer',
className: 'text-purple-600 line-through',
href: '/',
},
React.createElement('img', {
src: './customLogo.svg',
})
);
},
},
/** .. **/
};
```
![custom-logo](../assets/img/custom-logo.png)
You can use Tailwind CSS utility classes in the `className` property to style
your custom logo component.
## UI Services
While the component library handles what gets rendered, **UI services** handle
the runtime behavior: opening modals, showing notifications, managing viewport
layout, and coordinating dialogs. These services use a pub/sub architecture and
are accessed through the `servicesManager`:
| Service | What it manages |
|---------|----------------|
| [Modal Service](../platform/services/ui/ui-modal-service.md) | Full-screen and contained modals (including the Appearance dialog) |
| [Dialog Service](../platform/services/ui/ui-dialog-service.md) | Lightweight dialogs with form inputs and confirmations |
| [Notification Service](../platform/services/ui/ui-notification-service.md) | Toast notifications (success, warning, error, info) |
| [Viewport Grid Service](../platform/services/ui/viewport-grid-service.md) | Viewport layout, grid arrangement, and active viewport tracking |
| [Viewport Dialog Service](../platform/services/ui/ui-viewport-dialog-service.md) | Dialogs anchored to specific viewports |
| [Viewport Action Menu](../platform/services/ui/viewport-action-menu.md) | Context menus and action buttons on viewport corners |
| [Cine Service](../platform/services/ui/cine-service.md) | Cine playback controls and frame rate |
UI services are documented in the [Services > UI](../platform/services/ui/index.md)
section.
## Customization Service
The [Customization Service](../platform/services/customization-service/customizationService.md)
is the mechanism that ties everything together. It allows deployers and
extension authors to override, extend, or replace UI components and behaviors
without modifying core code. Customizations can be scoped to a specific mode, set
globally via configuration, or provided as defaults by extensions.
The Appearance dialog itself is delivered as a customization module. Deployers
enable it by adding a single reference to their config's `customizationService`
array. This pattern means that any part of the UI that supports customization
can be configured the same way.
See the full customization guide at
[Customization Service](../platform/services/customization-service/customizationService.md),
including the syntax reference for `$set`, `$push`, `$merge`, `$filter`, and
other operations.
+1 -1
View File
@@ -1,5 +1,5 @@
---
sidebar_position: 3
sidebar_position: 4
sidebar_label: URL
title: URL Parameters
summary: Reference for OHIF Viewer URL parameters that control WorkList filtering, study/series loading, and viewer behavior, including parameters for filtering by patient name, modality, data sources, specifying initial series/instances, and selecting hanging protocols.
@@ -6,10 +6,9 @@ title: 3.10 to 3.11 Migration Guide
---
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
# 3.10 to 3.11 Migration Guide
Here you can find the migration guides for upgrading from OHIF version 3.10 to version 3.11.
<DocCardList items={useCurrentSidebarCategory().items.filter(item => item.docId !== 'migration-guide/3p10-to-3p11/index')}/>
<DocCardList />
@@ -0,0 +1,99 @@
---
sidebar_position: 7
sidebar_label: Color System
title: Color System Migration
summary: 3.13 continues the migration from legacy color classes to the ui-next semantic color system. This guide maps legacy color names to their ui-next equivalents and shows common text, background, and border replacements.
---
# Color System Migration
This guide covers migrating from legacy color classes to the new ui-next color system.
## Current State (3.13+)
The OHIF Viewer is now built entirely with ui-next components, which use the [new color system](/colors-and-theming). The legacy components in `platform/ui` remain on the old color system. For reference, the table below maps the legacy colors to their ui-next equivalents.
## Color Mapping Reference
| Legacy Color | Updated color (ui-next) |
| ----------------- | ----------------------- |
| `bkg-low` | `background` |
| `common-bright` | `foreground` (various) |
| `primary-light` | `highlight` |
| `inputfield-main` | `input` |
| `secondary-light` | `input` |
| `primary-dark` | `muted` |
| `bkg-med` | `muted` |
| `aqua-pale` | `muted-foreground` |
| `secondary-dark` | `popover` |
| `primary-active` | `primary` |
| `actions-primary` | `primary` |
| `secondary-main` | |
| `primary-main` | |
| `common-dark` | |
| `customblue` | |
> **Note:** The legacy variables left blank in the table above (`secondary-main`, `primary-main`, `common-dark`, and `customblue`) have no direct ui-next equivalent. If your code uses any of these, replace them case by case, choosing the semantic token that best fits how the color is used in each component.
## Generic Color Migrations
Avoid using generic color values. Use semantic colors instead:
| Generic Color | Semantic Replacement |
| ---------------------------- | ----------------------- |
| `white` | `foreground` |
| `blue-*` (e.g., `blue-500`) | `primary` or `highlight`|
| `gray-*` (e.g., `gray-800`) | `muted` or `popover` |
| `red-*` | `destructive` |
> **Note:** `black` is still used in certain cases to replace default browser backgrounds and to match imaging backgrounds.
## Common Migrations
### Text Colors
```diff
- text-white
+ text-foreground
- text-primary-light
+ text-highlight
- text-primary-active
+ text-primary
- text-secondary-light
+ text-muted-foreground
```
### Background Colors
```diff
- bg-primary-dark
+ bg-muted
- bg-secondary-dark
+ bg-popover
- bg-black
+ bg-background
```
### Border Colors
```diff
- border-secondary-light
+ border-input
- border-primary-light
+ border-highlight
- border-primary-dark
+ border-muted
```
## Important Notes
- Legacy colors without a mapping (empty cells) should be evaluated on a case-by-case basis
- The new color system uses CSS variables, enabling future theme support
- When migrating, test components visually to ensure proper contrast and accessibility
@@ -6,7 +6,6 @@ title: 3.12 to 3.13 Migration Guide
---
import DocCardList from '@theme/DocCardList';
import { useCurrentSidebarCategory } from '@docusaurus/theme-common';
# 3.12 to 3.13 Migration Guide
@@ -25,4 +24,4 @@ The largest changes in 3.13 are infrastructure-level:
- **[SegmentationService](./segmentation-service.md)** — the
`removeSegmentationRepresentations` method was renamed.
<DocCardList items={useCurrentSidebarCategory().items.filter(item => item.docId !== 'migration-guide/3p12-to-3p13/index')} />
<DocCardList />
@@ -6,7 +6,6 @@ summary: Migration guide for segmentation architecture changes in OHIF 3.9, cove
---
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
:::info
This migration involves significant architectural changes to the segmentation system. While we typically aim for incremental updates, the shift from a tool group-centric to a viewport-centric architecture was necessary to support OHIF 3.9's advanced visualization capabilities, and more flexible segmentation handling.
@@ -15,4 +14,4 @@ Don't worry - we'll guide you through each change step by step!
:::
<DocCardList items={useCurrentSidebarCategory().items}/>
<DocCardList />
@@ -7,8 +7,7 @@ summary: Migration guide for upgrading from OHIF 3.8 to 3.9, covering segmentati
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
## Migration Guide Sections
<DocCardList items={useCurrentSidebarCategory().items}/>
<DocCardList />
@@ -12,7 +12,7 @@ summary: Migration guide for OHIF 3.10's new color system, explaining the transi
* **Component Abstraction:** Some styling, especially for interactive elements like buttons, has been abstracted into components (e.g., `ViewportActionButton`, UI library buttons) which use predefined variants (`default`, `secondary`, `ghost`) instead of manual style combinations.
:::note
You can look at the set of colors in the [Color System](/colors-and-type)
You can look at the set of colors in the [Color System](/colors-and-theming)
:::
@@ -13,7 +13,7 @@ This guide explains how to migrate from the existing `Input`, `InputNumber`, `In
## Why Migrate?
See the full list of components in the [Numeric Component Showcase](/components-list#numeric)
See the full list of components in the [Numeric Component](/components/numeric)
The old components relied heavily on props, making them complex and difficult to maintain and apply custom styles. The new `Numeric` component provides a structured approach with a context-based API, reducing prop clutter and improving reusability.
+1 -2
View File
@@ -6,10 +6,9 @@ summary: Introduction to OHIF migration guides covering the upgrade paths betwee
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
# Migration Guides
Based on the version you are migrating from, you can find the migration guide for the latest version of the platform.
<DocCardList items={useCurrentSidebarCategory().items}/>
<DocCardList />
@@ -1,7 +1,8 @@
---
sidebar_label: Measurements
title: Measurements Customization
summary: Documentation for customizing OHIF's measurement tools and displays, including how to modify display formats, annotation behaviors, and tracking interfaces for medical imaging measurements.
sidebar_position: 4
sidebar_position: 5
---
@@ -1,7 +1,8 @@
---
sidebar_label: Segmentation
title: Segmentation Customization
summary: Documentation for customizing OHIF's segmentation tools and visualization options, including configuration for segment rendering, color schemes, and interaction behaviors for medical image segmentation workflows.
sidebar_position: 5
sidebar_position: 6
---
@@ -1,7 +1,8 @@
---
sidebar_label: Study Browser
title: Study Browser Customization
summary: Documentation for customizing OHIF's Study Browser component, including configuration options for thumbnails, sorting functions, and display formats to enhance study navigation and selection workflows.
sidebar_position: 6
sidebar_position: 7
---
# Study Browser
@@ -1,7 +1,8 @@
---
sidebar_label: Viewport Scrollbar
title: Viewport Scrollbar Customization
summary: Documentation for configuring OHIF viewport scrollbar behavior, including progress vs legacy mode, loaded/viewed tracking visuals, loading pattern behavior, timing controls, and viewportScrollbar.indicator (size + optional custom indicator).
sidebar_position: 7
sidebar_position: 9
---
# Viewport Scrollbar
@@ -1,7 +1,8 @@
---
sidebar_label: Work List
title: Work List Customization
summary: Documentation for configuring the OHIF WorkList study-list route — selecting between the new (default) and legacy variants, the preview panel's series view (thumbnails, list, or both), and the columns shown in the study-list table.
sidebar_position: 9
sidebar_position: 10
---
# Work List
@@ -1,7 +1,8 @@
---
sidebar_label: Advanced
title: Advanced Customization
summary: Documentation for advanced OHIF customization techniques, including inheritance patterns, transform functions, and dynamic assembly of customizations to create sophisticated configurations across the platform.
sidebar_position: 8
sidebar_position: 11
---
@@ -0,0 +1,379 @@
---
sidebar_position: 2
sidebar_label: Appearance & Theming
title: Appearance & Theming
summary: Documentation for OHIF's appearance and theming system, including theme presets, custom themes, URL-based theme selection, and how to enable the Appearance dialog for your deployment.
---
# Appearance & Theming
OHIF includes an optional theming system that lets users switch between visual
theme presets, apply custom CSS token overrides, and share themes via URL. The
system is **not enabled by default** — deployers opt in by adding a single
configuration line.
## Enabling the Theme Module
The theming system is delivered as a customization module in the default
extension. To enable it, add the module reference to the `customizationService`
array in your configuration file:
```js
window.config = {
// ...
customizationService: [
'@ohif/extension-default.customizationModule.theme',
],
// ...
};
```
This single line activates the entire theming system:
- The **Appearance** menu item appears in the viewer header and study list
settings
- Users can switch between theme presets via a dropdown
- The active theme persists across sessions via `localStorage`
- Themes can be applied via URL parameter (`?theme=orchid`)
- Custom CSS token overrides can be pasted and applied
### What Happens Without It
When the theme module is not in the configuration:
- No Appearance menu item is shown anywhere in the UI
- No theme provider is mounted in the component tree
- URL parameters like `?theme=orchid` have no effect
- No `localStorage` keys are read or written
- Zero runtime footprint — the theming code does not execute
This opt-in design ensures that deployments that don't need theming pay no cost
for it.
## Theme Presets
OHIF ships with six built-in theme presets organized into two families:
### Tonal Presets
Tonal presets introduce a color hue throughout the interface — backgrounds,
borders, and surfaces all carry the theme's signature color.
| Preset | Description |
|--------|-------------|
| **Orchid** | Purple/violet tones with warm highlights |
| **Arctic** | Cool blue tones with icy surfaces |
| **Verdant** | Green tones with natural, earthy surfaces |
### Neutral Presets
Neutral presets keep surfaces achromatic (grays and blacks) and use color only
for interactive elements and highlights.
| Preset | Description |
|--------|-------------|
| **Midnight** | Deep blacks with subtle gray layering |
| **Slate** | Cool neutral grays with blue highlights |
| **Deep** | Rich dark surfaces with minimal contrast |
### Selecting a Preset
Open the Appearance dialog from the header menu (or study list settings) and
choose a preset from the Theme dropdown. The theme applies immediately and
persists across sessions.
## URL-Based Theme Selection
Themes can be applied via URL parameter, which is useful for sharing links with a
specific visual configuration:
```
https://your-ohif-instance.com/viewer?theme=orchid
```
Valid values are any preset name: `default`, `orchid`, `arctic`, `verdant`,
`midnight`, `slate`, `deep`.
The URL parameter takes precedence over the stored theme. When a URL theme is
applied, it is also saved to `localStorage` so the user's session continues with
that theme after navigation.
:::note
The `custom` theme value is deliberately not URL-addressable. Custom themes rely
on CSS stored in the user's `localStorage`, so a `?theme=custom` link would land
the app in a state with no CSS behind it.
:::
## Custom Themes
The Appearance dialog includes a custom theme feature that allows pasting CSS
variable overrides directly into the viewer.
### How It Works
1. Open the Appearance dialog
2. Click **Custom Theme** to expand the text area
3. Paste CSS variable declarations (one per line):
```css
--background: 270 45% 6%;
--foreground: 280 15% 96%;
--card: 268 40% 10%;
--primary: 270 85% 65%;
--border: 268 30% 18%;
```
4. Click **Apply**
The viewer parses the variables and injects them as CSS overrides into both
`:root` and `.dark` selectors. Invalid lines are silently skipped. If no valid
variables are found, the Apply button shows an error message.
Click **Clear** to remove the custom theme and return to the default appearance.
### Token Format
Theme tokens use **HSL triplets without the `hsl()` wrapper** — just the three
space-separated values:
```
--token-name: hue saturation% lightness%;
```
For example: `--primary: 270 85% 65%` represents a purple hue at 85% saturation
and 65% lightness.
### Available Tokens
The theming system uses the same token set as the base OHIF design system. The
most commonly customized tokens are:
| Token | Purpose |
|-------|---------|
| `--background` | Page/viewport background |
| `--foreground` | Default text color |
| `--card` | Surface color for cards and panels |
| `--popover` | Elevated surface color (dropdowns, tooltips) |
| `--primary` | Primary interactive color (buttons, links) |
| `--secondary` | Secondary surface color |
| `--muted` | Subdued background areas |
| `--muted-foreground` | Subdued text color |
| `--accent` | Accent surface color |
| `--border` | Border color |
| `--input` | Input field background |
| `--ring` | Focus ring color |
| `--highlight` | Highlight/selection color |
| `--destructive` | Error/destructive action color |
Each token also has a corresponding `-foreground` variant for text on that
surface (e.g., `--card-foreground`, `--primary-foreground`).
## Preset File Format
Theme presets are defined as JSON files in
`platform/ui-next/src/themes/`. Each file follows this structure:
```json
{
"name": "orchid",
"label": "Tonal: Orchid",
"cssVars": {
"dark": {
"highlight": "292 75% 62%",
"background": "270 45% 6%",
"foreground": "280 15% 96%",
"card": "268 40% 10%",
"primary": "270 85% 65%",
"border": "268 30% 18%"
}
}
}
```
| Field | Description |
|-------|-------------|
| `name` | Internal identifier. Must be unique and URL-safe. Used as the CSS class name (`theme-{name}`) and `?theme=` value. |
| `label` | Display label shown in the Appearance dialog dropdown. |
| `cssVars.dark` | Object mapping token names to HSL triplet values. Only tokens that differ from the default theme need to be specified. |
The corresponding CSS class is defined in `platform/ui-next/src/themes/themes.css`
and applies the token overrides when the class is added to `document.body`.
## Adding a Theme Preset
To add a new preset to the Appearance dialog dropdown, three files need to be
updated:
### 1. Create the JSON file
Add a new JSON file in `platform/ui-next/src/themes/`. Use an existing preset as
a template:
```json
{
"name": "ember",
"label": "Tonal: Ember",
"cssVars": {
"dark": {
"highlight": "15 85% 55%",
"background": "12 40% 5%",
"foreground": "20 15% 96%",
"card": "10 35% 9%",
"primary": "15 80% 50%",
"border": "12 25% 16%"
}
}
}
```
The `name` must be unique and URL-safe — it becomes the CSS class name
(`theme-ember`) and the `?theme=` URL value. Only include tokens that differ from
the default theme.
### 2. Add the CSS class to `themes.css`
Add a corresponding class in `platform/ui-next/src/themes/themes.css` with the
same token values:
```css
/* ─── Tonal: Ember ──────────────────────────────────────────────────── */
.theme-ember {
--highlight: 15 85% 55%;
--background: 12 40% 5%;
--foreground: 20 15% 96%;
--card: 10 35% 9%;
--primary: 15 80% 50%;
--border: 12 25% 16%;
/* ... all tokens from the JSON */
}
```
:::note
The JSON and CSS must define the same tokens with the same values. The JSON is
used for metadata (name, label) and validation. The CSS is what actually applies
the theme at runtime via the body class.
:::
### 3. Register in the barrel export
Import the JSON file and add it to the `themePresets` array in
`platform/ui-next/src/themes/index.ts`:
```ts
import orchid from './orchid.json';
import arctic from './arctic.json';
import verdant from './verdant.json';
import midnight from './midnight.json';
import slate from './slate.json';
import deep from './deep.json';
import ember from './ember.json'; // add import
export const themePresets: ThemePreset[] = [
orchid, arctic, verdant, midnight, slate, deep, ember // add to array
];
```
The order of the array determines the order in the dropdown menu.
## Removing a Theme Preset
To remove a preset, reverse the three steps above:
1. **Remove from `index.ts`** — delete the import and remove it from the
`themePresets` array
2. **Remove from `themes.css`** — delete the `.theme-{name}` class block
3. **Delete the JSON file** — remove the file from `platform/ui-next/src/themes/`
Users who had the removed theme active will fall back to the default theme on
their next visit — the provider validates stored theme names against the current
preset list and resets invalid values.
## Architecture
### How the Provider Registers
The theming system uses OHIF's `serviceProvidersManager` to register its React
provider dynamically. During app initialization, the default extension's
`preRegistration` hook checks whether the theme module is present in the
configuration. If it is, `ActiveThemeProvider` is registered into the component
tree:
```
App initializes
→ Default extension's preRegistration runs
→ Checks config for 'customizationModule.theme'
→ If present: registerProvider('activeTheme', ActiveThemeProvider)
→ App.tsx builds the provider tree
→ Picks up registered providers automatically
```
App.tsx has no knowledge of theming. The extension that provides the theme module
also decides whether to register its provider.
### How the Menu Item Appears
The Appearance menu item is gated by the customization service. Both the viewer
header (`ViewerHeader.tsx`) and the study list settings
(`StudyListSettingsPopover.tsx`) call:
```tsx
const AppearanceModal = customizationService.getCustomization('ohif.appearanceModal');
```
If the customization is not registered (because the theme module wasn't enabled),
the call returns `undefined` and no menu item is rendered.
### State Management
`ActiveThemeProvider` manages theme state via React context:
- **Active theme**: stored in component state and `localStorage` (`ohif:theme`)
- **Custom CSS**: stored in component state and `localStorage` (`ohif:custom-theme-css`)
- **CSS classes**: applied to `document.body` (`theme-{name}`)
- **Custom styles**: injected via a `<style>` element (`#ohif-custom-theme`)
The `useActiveTheme()` hook exposes the full API:
```tsx
const {
activeTheme, // Current theme name ('default', 'orchid', 'custom', etc.)
setActiveTheme, // Switch to a named preset
customCss, // Raw custom CSS text
applyCustomTheme, // Parse and apply custom CSS, returns boolean
clearCustomTheme, // Remove custom theme, revert to default
} = useActiveTheme();
```
## Configuration Reference
### Minimal Setup
```js
window.config = {
customizationService: [
'@ohif/extension-default.customizationModule.theme',
],
};
```
### With Other Customization Modules
The theme module can be combined with other customization modules:
```js
window.config = {
customizationService: [
'@ohif/extension-default.customizationModule.theme',
'@ohif/extension-cornerstone-dicom-seg.customizationModule.dicom-seg-sorts',
],
};
```
### Setting a Default Theme via URL
To link directly to a themed viewer session:
```
https://your-ohif-instance.com/viewer?StudyInstanceUIDs=1.2.3&theme=arctic
```
The theme parameter works alongside all other URL parameters.
@@ -1,6 +1,6 @@
---
sidebar_label: Custom Routes
sidebar_position: 2
sidebar_position: 4
title: Custom Routes
summary: Documentation for creating custom routes in OHIF, allowing extensions to define new URL paths and React components to extend the application with additional pages and navigation options.
---
@@ -543,4 +543,9 @@ needless to say if you opted to choose `name: default` in the `getCustomizationM
Below we are providing the example configuration for global scenario (using the configuration file), however, you can also use the `setCustomizations` method to set the customizations.
In addition to the parts listed in the table below, the
[Appearance & Theming](./appearance-theming.md) system is delivered as a
customization module (`@ohif/extension-default.customizationModule.theme`) that
adds theme preset switching, custom CSS overrides, and URL-based theme selection.
{TableGenerator(customizations)}
@@ -1,6 +1,6 @@
---
sidebar_label: Viewport Overlay
sidebar_position: 1
sidebar_position: 8
title: Viewport Overlay Customization
summary: Documentation for customizing OHIF's viewport overlays, allowing configuration of the information displayed in each corner (top-right, top-left, bottom-left, bottom-right) of medical imaging viewports.
---
-168
View File
@@ -1,168 +0,0 @@
---
sidebar_position: 2
sidebar_label: Theming
title: Theming the OHIF Viewer
summary: Documentation on customizing the visual appearance of the OHIF Viewer using Tailwind CSS and white-labeling capabilities, including how to modify the color scheme, add custom layouts via the LayoutTemplateModule, and replace the application logo with custom branding.
---
# Viewer: Theming
`OHIF-v3` has introduced the
[`LayoutTemplateModule`](./extensions/modules/layout-template.md) which enables
addition of custom layouts. You can easily design your custom components inside
an extension and consume it via the layoutTemplate module you write.
## Tailwind CSS
[Tailwind CSS](https://tailwindcss.com/) is a utility-first CSS framework for
creating custom user interfaces.
Below you can see a compiled version of the tailwind configs. Each section can
be edited accordingly. For instance screen size break points, primary and
secondary colors, etc.
```js
module.exports = {
prefix: '',
important: false,
separator: ':',
theme: {
screens: {
sm: '640px',
md: '768px',
lg: '1024px',
xl: '1280px',
},
colors: {
overlay: 'rgba(0, 0, 0, 0.8)',
transparent: 'transparent',
black: '#000',
white: '#fff',
initial: 'initial',
inherit: 'inherit',
indigo: {
dark: '#0b1a42',
},
aqua: {
pale: '#7bb2ce',
},
primary: {
light: '#5acce6',
main: '#0944b3',
dark: '#090c29',
active: '#348cfd',
},
secondary: {
light: '#3a3f99',
main: '#2b166b',
dark: '#041c4a',
active: '#1f1f27',
},
common: {
bright: '#e1e1e1',
light: '#a19fad',
main: '#fff',
dark: '#726f7e',
active: '#2c3074',
},
customgreen: {
100: '#05D97C',
},
customblue: {
100: '#c4fdff',
200: '#38daff',
},
},
},
};
```
You can also use the color variable like before. For instance:
```js
primary: {
default: ‘var(--default-color)‘,
light: ‘#5ACCE6’,
main: ‘#0944B3’,
dark: ‘#090C29’,
active: ‘#348CFD’,
}
```
## White Labeling
A white-label product is a product or service produced by one company (the
producer) that other companies (the marketers) rebrand to make it appear as if
they had made it -
[Wikipedia: White-Label Product](https://en.wikipedia.org/wiki/White-label_product)
Current white-labeling options are limited. We expose the ability to replace the
"Logo" section of the application with a custom "Logo" component. You can do
this by adding a whiteLabeling key to your configuration file.
```js
window.config = {
/** .. **/
whiteLabeling: {
createLogoComponentFn: function(React) {
return React.createElement(
'a',
{
target: '_blank',
rel: 'noopener noreferrer',
className: 'text-white underline',
href: 'http://radicalimaging.com',
},
React.createElement('h5', {}, 'RADICAL IMAGING')
);
},
},
/** .. **/
};
```
> You can simply use the stylings from tailwind CSS in the whiteLabeling
In addition to text, you can also add your custom logo
```js
window.config = {
/** .. **/
whiteLabeling: {
createLogoComponentFn: function(React) {
return React.createElement(
'a',
{
target: '_self',
rel: 'noopener noreferrer',
className: 'text-purple-600 line-through',
href: '/',
},
React.createElement('img', {
src: './customLogo.svg',
// className: 'w-8 h-8',
})
);
},
},
/** .. **/
};
```
The output will look like
![custom-logo](../assets/img/custom-logo.png)
<!--
Links
-->
<!-- prettier-ignore-start -->
[wikipedia]: https://en.wikipedia.org/wiki/White-label_product
<!-- prettier-ignore-end -->