Global Elements: Reusable Content of Blocks by kjac · Pull Request #22448 · umbraco/Umbraco-CMS

kjac · 2026-04-13T10:50:59Z

Description

Part of Global Elements — Phase 2. This adds Reusable Content of Blocks: a block in any Block Editor (Block List, Block Grid, Single Block, and Rich Text blocks) can now reference a shared Element from the Library instead of holding its own local content. Editing the Library Element updates every block that references it.

What you can do

Insert from Library — the block catalogue has a new Library tab for picking an existing Library Element to insert as a referenced block.
Transfer to Library — promote an existing local block to a reusable Library Element (you give it a name), so it can be reused elsewhere.
Disconnect from Library — break the reference on a single block. This creates a local copy of the Element's content; the Library Element itself is left unchanged.
Edit in place — edit a referenced Element's content directly from within the block editor.
Publish awareness — referenced blocks surface the publish state of the underlying Library Element (e.g. an unpublished indicator).
Usage visibility — referenced Elements show how many items reference them ("This Element is referenced by N item(s).").

Referenced blocks are visually distinguished from local blocks with a dedicated reference colour.

Behind the scenes

Reusable Elements are indexed for search and resolved for published output rendering across all block property editors (Block List, Block Grid, Single Block, RTE). New IBlockElementService / BlockElementService resolve shared element content.
Block layout items now carry a structural key (distinct from contentKey), and block identity is keyed on the layout key. This lets the same Element be referenced by multiple layout items unambiguously.

Breaking change

UmbBlockLayoutBaseModel now requires a key: string property. Plugin/extension code that constructs block layout objects directly must supply a key. Persisted data without a key is handled on load (a key is derived from the existing contentKey).

How to test

Create or open content using a Block List, Block Grid, Single Block, or RTE-with-blocks property.
Transfer to Library: add a block, fill in its content, then use the block action to Transfer to Library; give it a name. Confirm it appears in the Element Library.
Insert from Library: add another block and choose the Library tab; pick the Element you just created. Confirm it renders as a referenced (coloured) block.
Edit in place: edit the referenced Element's content from the block; confirm the change is reflected on every block that references it.
Disconnect: use Disconnect from Library on one referenced block; confirm it becomes a local copy and the Library Element are unaffected.
Publish/render: publish and view the page on the front-end; confirm referenced block content renders. Confirm reusable Element content is findable via search.
Reference count: confirm the Element reports the correct number of referencing items.

A block layout item's contentKey can point to either local inline content or a library element. For shared content, the `isSharedContent` flag is set to `true`.

Critical: - disconnectFromLibrary now sets initial expose for new local content and cleans up resolved variant state entry - Extract #updateExposedState() in entry elements, called from all three observers (hasExpose, isLibraryElement, sharedContentVariantState) to prevent stale unpublished state on library blocks Important: - Guard #fetchLibraryElement against already-resolved elements to prevent redundant server requests - Hoist UmbElementDetailRepository to class field in entry elements to avoid accumulating dead controllers Suggestion: - Fix umb-localize key attributes to use literal keys instead of resolved strings from localize.term()

…rch and output rendering

# Conflicts: # src/Umbraco.Web.UI.Client/src/packages/block/block/context/block-entry.context.ts

- Use DocumentVariantStateModel.DRAFT enum instead of magic string in both block-list and block-grid entry elements - Strip isSharedContent from layout during clipboard write to prevent pasted blocks from incorrectly appearing as library references - Guard #setInitialBlockExpose in disconnectFromLibrary against missing content type structure - Store all element variants and resolve against active variantId for correct multi-culture state display - Add already-resolved guard to #fetchLibraryElement - Add JSDoc on isLibraryElement and sharedContentVariantState observables - Add .trim() to transfer modal name validation

BREAKING: UmbBlockLayoutBaseModel now requires a `key: string` property. Plugin code that creates layout objects without `key` will get a compile error. - Change UmbArrayState identity functions to use `(x) => x.key` - Add `layout` setter on entry elements (list, grid, single, rte) that extracts both layoutKey and contentKey from the layout object - Deprecate `contentKey` setter on entry elements (use `layout` instead) - Add `layoutKey` read-only getter for sorter identity - Add `setLayoutKey()` / `layoutByKey()` / `getLayoutByKey()` methods - Update `transferToLibrary` and `disconnectFromLibrary` to take layoutKey - Update delete operations to find by layout key, only remove shared content/settings/exposes if no other layout references the same contentKey - Migrate grid recursive area operations to use key for identity - Update `unique` observable on entry context to derive from layout key - Generate new key on property value clone - Backwards compat: `setLayouts` assigns `key ??= contentKey` for persisted data without key - Strip `isSharedContent` from clipboard layout clone - Update sorter configs and repeat key functions

- requestTransferToElementLibrary / requestDisconnectFromElementLibrary → requestTransferToExternalContent / requestDisconnectFromExternalContent (manager + entry context + action callers) - .addAdditionalPath('library') → 'element' - #resolvedExternalContent / #resolvedExternalContentVariants → #externalContentValues / #externalContentVariants - elementStateOf → externalContentStateOf - hrefObservable / validationDataPathObservable → href / validationDataPath (interface + action impls + default kind element) - _hasExpose → _localExpose (grid, list, single entry elements) - BlockWorkspaceHasContentConditionConfig / BlockEntryHasSettingsConditionConfig: type alias → interface - Remove implementation-specific / AI-ish comments from block-entry, block-manager, action files, block-workspace - Reuse #elementRepository field in requestTransfer/Disconnect; remove local instantiations - #fetchExternalContent now accepts an array — one call per layout-state update instead of N - getHref / getValidationDataPath in edit-content/edit-settings actions now resolve via the observable

…s empty-interface rule

github-actions · 2026-06-19T15:06:32Z

Azure Static Web Apps: Your stage site is ready! Visit it here: https://victorious-ground-017b08103-22448.westeurope.6.azurestaticapps.net

github-actions · 2026-06-19T15:10:35Z

Azure Static Web Apps: Your stage site is ready! Visit it here: https://orange-sea-0c7411a03-22448.westeurope.6.azurestaticapps.net

leekelleher and others added 9 commits April 10, 2026 17:39

Slice 1: Reference Model

3bb4d7e

A block layout item's contentKey can point to either local inline content or a library element. For shared content, the `isSharedContent` flag is set to `true`.

Slice 2: Insert Block from Library

a443a26

Slice 3: Transfer to Library

b07596c

Slice 4: Disconnect from Library

e15cf06

Slice 5: Inline Element Editing from Block Context

35174f6

[WIP] Slice 6: Publish Awareness

520e4b7

Merge branch 'v18/dev' into v18/feature/reusable-block-content

1f19bcb

Enable reusable elements in block editors, including indexing for sea…

cfdfda6

…rch and output rendering

leekelleher changed the title ~~Elements: Reusable block content (WIP)~~ [WIP] Global Elements: Reusable Content of Blocks Apr 13, 2026

leekelleher added type/feature area/frontend area/backend labels Apr 13, 2026

kjac and others added 6 commits April 14, 2026 09:15

Update cache levels for property value converters.

44fb633

Merge branch 'v18/dev' into v18/feature/reusable-block-content

a901550

# Conflicts: # src/Umbraco.Web.UI.Client/src/packages/block/block/context/block-entry.context.ts

Add keys to block layout items

91f6f8a

Merge branch 'v18/dev' into v18/feature/reusable-block-content

dc82922