pimcore/pimcore-studio-ui-widgets

What This Skill Covers

Working with the Pimcore Studio UI widget system: registering widgets, opening them in layout areas (main/left/right/bottom), configuring tabs via WidgetManagerTabConfig, and connecting widgets to main navigation.

When to Use This Skill

• Creating a feature that needs its own panel/tab in Studio UI
• Registering a custom widget component
• Opening widgets programmatically
• Connecting a widget to a main navigation entry
• Building singleton or multi-instance widget tabs

Import Paths

BEFORE writing any import, read CRITICAL-IMPORT-PATHS.md.

Examples below use bundle imports (@pimcore/studio-ui-bundle/*). For core development (@sdk/*, @Pimcore/*), see the referenced file.

Widget Registry

Widgets must be registered before they can be opened. Registration happens during module initialization via the WidgetRegistry service.

import { type WidgetRegistry } from '@pimcore/studio-ui-bundle/modules/widget-manager'
import { container, serviceIds } from '@pimcore/studio-ui-bundle/app'
import { MyWidgetComponent } from './my-widget-component'

const widgetRegistryService = container.get<WidgetRegistry>(serviceIds.widgetManager)

widgetRegistryService.registerWidget({
  name: 'my-widget',
  component: MyWidgetComponent
})

• name is the identifier used later in WidgetManagerTabConfig.component
• component must be a React component (named export, not default)
• Register in your module's onInit before any code tries to open the widget

Widget Interface

interface Widget {
  name: string
  component: ComponentType
  titleComponent?: ComponentType
  contentTitleComponent?: ComponentType
  isModified?: (tabNode: TabNode) => boolean
  getContextProvider?: (context, children) => React.JSX.Element
  defaultGlobalContext?: boolean
  transformConfig?: (config) => config
  isVisible?: (widget: WidgetConfig) => boolean
}

| Property | Type | Required | Description | |----------|------|----------|-------------| | name | string | Yes | Unique identifier for the widget | | component | ComponentType | Yes | React component rendered as the widget body | | titleComponent | ComponentType | No | Custom component for the tab title | | contentTitleComponent | ComponentType | No | Custom component for the content area title bar | | isModified | (tabNode) => boolean | No | Whether the widget has unsaved changes (shows tab indicator) | | getContextProvider | (context, children) => JSX.Element | No | Wraps the widget in a context provider | | defaultGlobalContext | boolean | No | Whether to use global context by default | | transformConfig | (config) => config | No | Transform the widget config before rendering | | isVisible | (widget) => boolean | No | Dynamic visibility of the widget |

Most widgets only need name and component.

Widget Areas

Pimcore Studio UI uses a flexible layout with four widget areas:

┌──────────────────────────────────────────────────────┐
│                    Toolbar / Navigation              │
├──────────┬───────────────────────────┬───────────────┤
│          │                           │               │
│   LEFT   │          MAIN             │    RIGHT      │
│          │        (center)           │               │
│          ├───────────────────────────┤               │
│          │         BOTTOM            │               │
├──────────┴───────────────────────────┴───────────────┤
│                      Status Bar                      │
└──────────────────────────────────────────────────────┘

| Area | Purpose | Typical Use | |------|---------|-------------| | main | Center content area | Editors, listings, dashboards | | left | Left sidebar | Tree navigation, filters | | right | Right sidebar | Properties, details panels | | bottom | Bottom panel | Logs, console output, search results |

Feature widgets usually open in main. Tree views and navigation panels typically go in left.

useWidgetManager Hook

import { useWidgetManager, type WidgetManagerTabConfig } from '@pimcore/studio-ui-bundle/modules/widget-manager'

const widgetManager = useWidgetManager()

| Method | Description | |--------|-------------| | openMainWidget(config) | Open widget in center area | | openLeftWidget(config) | Open widget in left sidebar | | openRightWidget(config) | Open widget in right sidebar | | openBottomWidget(config) | Open widget in bottom panel | | closeWidget(id) | Close a widget by its ID | | switchToWidget(id) | Focus an already-open widget |

All four open*Widget methods take the same WidgetManagerTabConfig shape — pick the one matching the target area.

Usage Example

export const MyComponent = (): React.JSX.Element => {
  const widgetManager = useWidgetManager()

  const openMyFeature = (): void => {
    const tabConfig: WidgetManagerTabConfig = {
      name: 'My Feature',
      id: 'my-feature-singleton',
      component: 'my-feature',
      config: {
        translationKey: 'my-feature.title',
        icon: { type: 'name', value: 'widget-default' }
      }
    }

    widgetManager.openMainWidget(tabConfig)
  }

  return <Button onClick={ openMyFeature }>Open Feature</Button>
}

WidgetManagerTabConfig

interface WidgetManagerTabConfig {
  name: string
  id?: string
  component: string
  config: {
    translationKey?: string
    label?: string
    icon?: { type: 'name', value: string }
    [key: string]: any
  }
}

| Property | Type | Required | Description | |----------|------|----------|-------------| | name | string | Yes | Display name for the tab | | id | string | No | Unique ID. Auto-generated if omitted. Set a fixed value for singletons. | | component | string | Yes | Must match a registered widget's name | | config | object | Yes | Configuration passed to the widget component | | config.translationKey | string | No | Translation key for the tab label | | config.label | string | No | Static label (prefer translationKey) | | config.icon | object | No | Icon displayed on the tab | | config.[key] | any | No | Any additional data the widget needs (e.g., assetId) |

The config object is flexible — add any properties the widget component needs (e.g., assetId, mode, parentFolderId). Access them inside the widget via the widget context or props.

Full Example: Widget + Registration + Navigation

End-to-end example showing a widget wired into main navigation.

1. Widget Component

// your-bundle/assets/studio/js/src/modules/my-feature/components/my-feature-widget.tsx
import React from 'react'
import { Content, Header, Select, Button } from '@pimcore/studio-ui-bundle/components'
import { useTranslation } from 'react-i18next'

export const MyFeatureWidget = (): React.JSX.Element => {
  const { t } = useTranslation()

  return (
    <Content padded>
      <Header title={ t('my-feature.title') }>
        <Button type="primary" onClick={ () => {} }>
          { t('my-feature.action-button') }
        </Button>
      </Header>
      <p>{ t('my-feature.description') }</p>
    </Content>
  )
}

2. Module: Register Widget + Nav Item

// your-bundle/assets/studio/js/src/modules/my-feature/index.ts
import { type AbstractModule } from '@pimcore/studio-ui-bundle'
import { container, serviceIds } from '@pimcore/studio-ui-bundle/app'
import { type WidgetRegistry } from '@pimcore/studio-ui-bundle/modules/widget-manager'
import { type MainNavRegistry } from '@pimcore/studio-ui-bundle/modules/app'
import { MyFeatureWidget } from './components/my-feature-widget'

export const MyFeatureModule: AbstractModule = {
  onInit: (): void => {
    const widgetRegistryService = container.get<WidgetRegistry>(serviceIds.widgetManager)
    widgetRegistryService.registerWidget({
      name: 'my-feature',
      component: MyFeatureWidget
    })

    const mainNavRegistry = container.get<MainNavRegistry>(serviceIds.mainNavRegistry)
    mainNavRegistry.registerMainNavItem({
      path: 'DataManagement/My Feature',
      label: 'my-feature.navigation.title',
      order: 10,
      perspectivePermission: 'dataManagement.myFeature',
      widgetConfig: {
        name: 'My Feature',
        id: 'my-feature',
        component: 'my-feature',  // Must match registered widget name
        config: {
          translationKey: 'my-feature.navigation.title',
          icon: { type: 'name', value: 'widget-default' }
        }
      }
    })
  }
}

3. Register Module in Plugin

// your-bundle/assets/studio/js/src/plugin.ts
import { type AbstractPlugin } from '@pimcore/studio-ui-bundle'
import { MyFeatureModule } from './modules/my-feature'

export const YourBundlePlugin: AbstractPlugin = {
  modules: [MyFeatureModule]
}

4. Translations

# your-bundle/translations/studio.en.yaml
my-feature:
  navigation:
    title: My Feature
  title: My Feature
  description: This is my custom feature widget.
  action-button: Run action

perspective-editor:
  form:
    main-nav-permission:
      dataManagement:
        myFeature: Data Management > My Feature

Connecting a Widget to Navigation

The component field in widgetConfig is a string that must exactly match the name passed to registerWidget(). This is how the widget manager resolves which React component to render when the nav item is clicked.

// Register with name 'my-feature'
widgetRegistryService.registerWidget({
  name: 'my-feature',        // <-- This name...
  component: MyFeatureWidget
})

// Reference in navigation's widgetConfig
mainNavRegistry.registerMainNavItem({
  path: 'DataManagement/My Feature',
  label: 'my-feature.navigation.title',
  widgetConfig: {
    component: 'my-feature',  // <-- ...must match here
    name: 'My Feature',
    id: 'my-feature',
    config: {
      translationKey: 'my-feature.navigation.title',
      icon: { type: 'name', value: 'widget-default' }
    }
  }
})

Widgets don't require a navigation entry — you can open them from any component by calling widgetManager.openMainWidget(config) (or any other open*Widget variant).

Singleton vs Multi-Instance Widgets

| Pattern | ID strategy | Behavior | Use for | |---------|-------------|----------|---------| | Singleton | Fixed id | Re-opening switches to existing tab | Settings, listings, dashboards | | Multi-instance | Omit id or use dynamic id (e.g. asset-editor-${assetId}) | Each open creates a new tab | Element editors, detail views, comparisons |

// Singleton: always the same tab
{ name: 'Settings', id: 'settings', component: 'settings', config: { /* ... */ } }

// Multi-instance: new tab per asset
{ name: `Asset ${assetId}`, id: `asset-editor-${assetId}`, component: 'asset-editor',
  config: { assetId, /* ... */ } }

Common Mistakes

Referencing an unregistered widget in navigation

// ❌ WRONG - Widget was never registered, fails silently
mainNavRegistry.registerMainNavItem({
  widgetConfig: { component: 'my-feature', /* ... */ }
})

// ✅ CORRECT - Register first, then reference
widgetRegistryService.registerWidget({ name: 'my-feature', component: MyFeatureWidget })
mainNavRegistry.registerMainNavItem({
  widgetConfig: { component: 'my-feature', /* ... */ }
})

Default export instead of named export

// ❌ WRONG
const MyWidget = () => <div>Hello</div>
export default MyWidget

// ✅ CORRECT
export const MyWidget = (): React.JSX.Element => <div>Hello</div>

Case mismatch between registered name and widgetConfig.component

// ❌ WRONG - Case-sensitive mismatch
registerWidget({ name: 'my-feature', component: MyFeatureWidget })
widgetConfig: { component: 'My-Feature' }

// ✅ CORRECT - Exact string match
widgetConfig: { component: 'my-feature' }

Missing icon in config

// ❌ Tab looks incomplete without an icon
config: { translationKey: 'my-feature.title' }

// ✅ Always provide an icon
config: {
  translationKey: 'my-feature.title',
  icon: { type: 'name', value: 'widget-default' }
}

Not setting ID for singleton widgets

Omitting id on a nav-linked widget opens a new tab on every click. Set a fixed id for singletons.

Next Steps

• pimcore-studio-ui-navigation - Main navigation entries and perspective permissions
• pimcore-studio-ui-tabs-editors - Tabbed editor interfaces within widgets
• pimcore-studio-ui-context-menus - Context menu actions that open widgets