> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open-metadata.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Breaking Changes - UI & Customization | Official Documentation

> Design-system consolidation, App Mode, persona preferences, Context Center and removed UI components in OpenMetadata 2.0.

# UI, Personas & Customization

For end users this is a visual and navigational refresh. For anyone who forks the UI, writes a UI
plugin, or maintains end-to-end test suites, it is a large refactor.

The Explore page changes are documented separately in
[Discovery & Search](/v2.0.x-SNAPSHOT/deployment/upgrade/breaking-changes/discovery-and-search).

## Design system consolidation

<Warning>
  **Breaking for forks and plugins.** Cosmetic for end users.
</Warning>

1.13 carried a transitional set of `MUI*` wrapper components inside the UI module. 2.0 removes them
and standardises on the shared **`@openmetadata/ui-core-components`** package.

### Removed component modules

```
components/common/MUISelect/                 components/common/MUITextField/
components/common/MUIUserTeamSelect/         components/common/MUIDomainSelect/
components/common/MUIFormItemLabel/          components/common/MUIGlossaryTagSuggestion/
components/common/MUIAsyncTreeSelect/**      components/common/MuiDatePickerMenu/
components/common/MuiDrawer/                 components/common/ColorPicker/MUIColorPicker.tsx
components/common/IconPicker/MUIIconPicker.tsx
components/common/CoverImageUpload/MUICoverImageUpload.tsx
components/common/FileUpload/MUIFileUpload.tsx
components/common/DeleteModal/DeleteModalMUI.tsx
components/form/MUIAutocomplete/
components/common/atoms/asyncTreeSelect/**
components/common/atoms/navigation/useSearch.tsx
components/common/atoms/navigation/useBreadcrumbs.tsx
components/common/atoms/navigation/useViewToggle.tsx
components/common/atoms/pagination/usePaginationControls.tsx
components/common/atoms/notifications/NotificationMessage.tsx
components/common/atoms/table/TagsCell.tsx
components/common/atoms/data/useQueryBuilder.tsx
```

The **`SELECT_MUI` field type is removed** from the form builder.

### Other removed UI modules

| Removed                                                                                | Replacement                                             |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `components/CondensedBreadcrumb/**`                                                    | core-components `Breadcrumbs`                           |
| `components/common/EntityDescription/DescriptionV1.tsx`                                | new description components                              |
| `components/Modals/DeleteModal/**`, `EntityDeleteModal/**`, `DeleteWidgetModal.tsx`    | consolidated delete modal                               |
| `components/ActivityFeed/ActivityFeedCardV2/**`, `FeedCardBodyV1.tsx`, `TaskBadge.tsx` | activity-stream components                              |
| `components/KnowledgeGraph/**`                                                         | RDF-backed 3D graph in `components/OntologyExplorer/**` |
| `components/Entity/EntityList/EntityList.tsx`                                          | shared listing atoms                                    |
| `components/DataQuality/AddDataQualityTest/**`                                         | react-hook-form based forms                             |
| `components/SearchSettings/FilterConfiguration/FilterConfiguration.tsx`                | new search-settings UI                                  |
| `pages/LogsViewerPage/**`                                                              | `LogViewerModal` with live log streaming                |
| `utils/CommonUtils.tsx`                                                                | split into domain-specific utility modules              |
| `utils/NotistackUtils.tsx`, `hooks/useAlertStore.ts`                                   | `ToastUtils` plus core-components `Toast`               |
| `utils/TasksUtils.ts`, `utils/KnowledgeGraph.utils.ts`, `utils/LogsClassBase.ts`       | redesigned equivalents                                  |
| `constants/Tags.constant.ts`                                                           | inlined or relocated                                    |
| `components/Settings/Applications/AppLiveIndexing/**`                                  | `components/OntologyExplorer/**`                        |

<Tip>
  Search your fork for `MUI` imports, `SELECT_MUI`, `usePaginationControls`, `NotistackUtils`,
  `CommonUtils` and `DescriptionV1`. Expect a mechanical but wide migration. `PaginationCardDefault`
  replaces `usePaginationControls`, and `Input` from core-ui replaces the `useSearch` hook.
</Tip>

### New extension points

<Info>
  **Additive** — these are the supported way to customise in 2.0.
</Info>

| Extension point                           | Purpose                                                  |
| ----------------------------------------- | -------------------------------------------------------- |
| `ObservabilityRouterClassBase`            | Override data quality and observability navigation paths |
| `ConnectionsRouterClassBase`              | Pluggable connection routing                             |
| `EntityUtilClassBase.getEntityTypes()`    | Overridable entity-type list                             |
| App Mode primitives and routes registry   | Downstream plugin routes                                 |
| Extensible user-profile dropdown items    | Add items to the profile menu                            |
| `withDomainFilter` higher-order component | Domain-scoped list pages                                 |
| `brandName`                               | Replaces hard-coded product strings for white-labelling  |

## App Mode

<Info>
  **New concept.** Affects the login experience and persona configuration.
</Info>

2.0 introduces two application experiences — **Classic** (the standard OpenMetadata UI) and **AI**
(the assistant-driven experience, which requires the AI plugin).

Resolution order, highest priority first:

1. **User preference** — the `appMode` entry in the user's preferences bag
2. **Persona `appMode`** — `classic` or `AI` (default `classic`), forced on login
3. **Tenant `defaultAppMode`** — the `appConfiguration` setting

```json theme={null}
{ "type": "appMode", "config": { "value": "ai" | "classic" | null } }
```

The active mode is held in a single source of truth backed by session storage, so sibling tabs no
longer lose the active mode.

<Note>
  Setting a persona's `appMode` to `AI` on OpenMetadata OSS has no effect beyond the mode flag — the AI
  experience ships with the Collate distribution.
</Note>

## Per-user preferences API

<Info>
  **New API**, backed by a new `user_preferences` table.
</Info>

```
GET    /v1/users/{userId}/preferences
PUT    /v1/users/{userId}/preferences/{type}
DELETE /v1/users/{userId}/preferences/{type}
```

```json theme={null}
{
  "userId": "…",
  "preferences": [ { "type": "appMode", "config": { "value": "classic" } } ],
  "updatedAt": 1712345678000
}
```

The preferences bag is a typed discriminated union keyed by `type`. It is deliberately **not** a full
entity — no versioning, audit or soft-delete — and is cascade-deleted with the user.

<Tip>
  Do not store per-user UI state in the User entity's `extension`. Use the preferences API.
</Tip>

## Personas gain AI context

<Info>
  **Additive** (Collate AI features).
</Info>

Personas gain a `contextDefinition` field — *"rules and settings used to materialize the shared AI
context for this persona"* — plus new endpoints:

```
GET  /v1/personas/search
GET  /v1/personas/me/context
GET  /v1/personas/{id}/context
GET  /v1/personas/name/{fqn}/context
GET  /v1/personas/{id}/aiContext
PUT  /v1/personas/{id}/aiContext
POST /v1/personas/{id}/aiContext/rules
POST /v1/personas/{id}/aiContext/rules/preview
```

## Context Center & Knowledge Center

<Info>
  **New routes.** Affects navigation and reverse proxies.
</Info>

```
/knowledge-center
/context-center
/context-center/dashboard    /context-center/articles     /context-center/documents
/context-center/filter       /context-center/memories     /context-center/integrations
/context-center/archive
```

New REST namespaces: `/v1/contextCenter/pages`, `/v1/contextCenter/memories`,
`/v1/contextCenter/drive/files`, `/v1/contextCenter/drive/folders` and `/v1/attachments`. New
entities: `page`, `article`, `quickLink`, `pageHierarchy`, `folder`, `contextFile`,
`contextFileContent`, `contextMemory` and `asset`.

<Warning>
  If you front OpenMetadata with a proxy that allowlists paths, add `/knowledge-center`,
  `/context-center`, `/api/v1/contextCenter` and `/api/v1/attachments`. Uploads require object storage
  to be enabled — see
  [Platform & Security](/v2.0.x-SNAPSHOT/deployment/upgrade/breaking-changes/platform-and-security).
</Warning>

## Visual and navigation changes

<Note>
  **Behavioural.** Affects end users, screenshots in your internal documentation, and end-to-end tests.
</Note>

| Change                   | Detail                                                                                                    |
| ------------------------ | --------------------------------------------------------------------------------------------------------- |
| **Entity page header**   | Redesigned to the 2.0 card layout                                                                         |
| **Dark theme**           | Supported via design tokens                                                                               |
| **Owner display**        | Multi-owner headers stack avatars with a hover popover                                                    |
| **Announcements**        | Rendered in the entity header, not only in the feed widget                                                |
| **Sidebar**              | "Marketplace" renamed to **Data Marketplace** / **Overview**                                              |
| **Agents tab**           | Revamped agent listing and details wired to real data                                                     |
| **Service icons**        | Migrated from PNG to WebP                                                                                 |
| **Glossary Terms table** | Adaptable search, column resize, drag reorder, sticky header                                              |
| **Landing page**         | Widgets lazy-loaded; admins can set a default panel colour                                                |
| **Log viewer**           | Modal with live streaming, replacing the standalone Logs Viewer page                                      |
| **Empty states**         | New prefilled placeholder variants across glossary, classification, metric, domain and data-product pages |
| **Toasts**               | Consolidated on the core-components toast provider                                                        |
| **Permission errors**    | `403` responses surface a proper toast                                                                    |
| **Asset Health widget**  | Added to the table detail page                                                                            |
| **Language**             | Swedish (`sv-SE`) added; the UI sends an `X-OpenMetadata-Language` header                                 |

<Tip>
  Expect widespread `data-testid` and DOM-structure churn. Budget for an end-to-end test refresh.
</Tip>

## Performance refactor (fork-visible)

<Note>
  **Behavioural.** Affects forks with deep imports.
</Note>

2.0 does a large code-splitting and lazy-loading pass:

* Pure utility functions are extracted into `*PureUtils` modules.
* `utils/CommonUtils.tsx` and `utils/EntityUtils.tsx` are deleted; facade imports are migrated to
  direct sources.
* Settings, entity and entity-import routers, tab-level components and heavy components are lazy-loaded.
* The build configuration is reworked for code splitting and chunk loading.

<Tip>
  Deep imports from `utils/CommonUtils` or `utils/EntityUtils` will not resolve. Import from the specific
  domain module instead.
</Tip>

## Component library

<Info>
  **Additive.** The shared component package gains `Breadcrumbs`, `EmptyPlaceholder`, `ProgressSteps`,
  `Toast`, a filter bar, an extra-small button size and a nightly Storybook build.
</Info>

Two renames to be aware of when consuming the package: safe class renames applied across components,
and the Select-family `placeholderIcon` prop renamed to **`icon`**.