# umbraco-ufm-component

Guides building Umbraco Flavored Markdown components, custom markers that render extra content in backoffice text.

Skill by Umbraco. Category: Web and browsers.

## Install

Project (for this project only):

```sh
npx skills add umbraco/umbraco-cms-backoffice-skills --skill umbraco-ufm-component
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add umbraco/umbraco-cms-backoffice-skills --skill umbraco-ufm-component -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Warn
- Runlayer: Warn

Installs: 352. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/umbraco/umbraco-cms-backoffice-skills/umbraco-ufm-component)

## Source

[Open the source](https://github.com/umbraco/umbraco-cms-backoffice-skills/tree/HEAD/plugins/umbraco-backoffice-skills/skills/umbraco-ufm-component). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: umbraco-ufm-component
description: Implement UFM (Umbraco Flavored Markdown) components in Umbraco backoffice using official docs
version: 1.0.1
location: managed
allowed-tools: Read, Write, Edit, WebFetch
---

# Umbraco UFM Component

## What is it?
UFM (Umbraco Flavored Markdown) Components extend Umbraco's markdown rendering with custom syntax. They allow you to create custom markers that transform into HTML when rendered. This is useful for creating dynamic content like localized strings, property values, or custom UI elements within markdown text. UFM components use special syntax markers (like `#` for localization or `=` for values) that get processed into HTML.

## Documentation
Always fetch the latest docs before implementing:

- **Foundation**: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation
- **Extension Registry**: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-registry
- **UFM**: https://docs.umbraco.com/umbraco-cms/model-your-content/property-editors/umbraco-flavored-markdown

## Reference Example

The Umbraco source includes a working example:

**Location**: `/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/ufm-custom-component/`

This example demonstrates a custom UFM component with marker syntax. Study this for production patterns.

## Related Foundation Skills

- **Localization**: When creating localized UFM components
  - Reference skill: `umbraco-localization`

- **Context API**: When accessing data for UFM rendering
  - Reference skill: `umbraco-context-api`

## Workflow

1. **Fetch docs** - Use WebFetch on the URLs above
2. **Ask questions** - What marker? What output? Dynamic data?
3. **Generate files** - Create manifest + component based on latest docs
4. **Explain** - Show what was created and how to test

## Minimal Examples

### Manifest (manifests.ts)
```typescript
import type { ManifestUfmComponent } from '@umbraco-cms/backoffice/ufm';

export const manifests: Array<ManifestUfmComponent> = [
  {
    type: 'ufmComponent',
    alias: 'My.UfmComponent.Custom',
    name: 'Custom UFM Component',
    api: () => import('./my-ufm-component.js'),
    meta: {
      alias: 'myCustom',  // Usage: {myCustom:value}
      marker: '%',        // Optional: Short marker like {%value}
    },
  },
];
```

### Component Implementation (my-ufm-component.ts)
```typescript
import { UmbUfmComponentBase } from '@umbraco-cms/backoffice/ufm';
import type { UfmToken } from '@umbraco-cms/backoffice/ufm';

export class MyUfmComponent extends UmbUfmComponentBase {
  render(token: UfmToken): string | undefined {
    // token.text contains the text after the marker
    // e.g., {%hello} would have token.text = 'hello'

    return `<span class="my-custom">${token.text}</span>`;
  }
}

export { MyUfmComponent as api };
```

### Component with Custom Element (my-ufm-component.ts)

> **Important**: UFM's post-processing sanitizer only allows custom element
> tag names that start with `umb-`, `ufm-`, or `uui-`. Any other prefix
> (e.g. `my-hidden-label`) will be stripped from the rendered output.
> See the [UFM sanitization docs](https://docs.umbraco.com/umbraco-cms/model-your-content/property-editors/umbraco-flavored-markdown#post-processing-and-sanitization).

```typescript
import { html, customElement, property } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { UmbUfmComponentBase } from '@umbraco-cms/backoffice/ufm';
import type { UfmToken } from '@umbraco-cms/backoffice/ufm';

// The UFM component that renders to custom element
export class MyUfmComponent extends UmbUfmComponentBase {
  render(token: UfmToken): string | undefined {
    // Output a custom element with the token text as attribute.
    // Tag name MUST start with umb-, ufm-, or uui- to survive sanitization.
    return `<ufm-my-element text="${token.text}"></ufm-my-element>`;
  }
}

// The custom element that gets rendered
@customElement('ufm-my-element')
export class MyUfmElement extends UmbLitElement {
  @property()
  text?: string;

  override render() {
    return html`<strong>${this.text}</strong>`;
  }
}

export { MyUfmComponent as api };
```

### Highlight Component Example
```typescript
import { UmbUfmComponentBase } from '@umbraco-cms/backoffice/ufm';
import type { UfmToken } from '@umbraco-cms/backoffice/ufm';

// Usage: {!important text here} or {highlight:important text here}
export class HighlightUfmComponent extends UmbUfmComponentBase {
  render(token: UfmToken): string | undefined {
    return `<mark style="background: yellow; padding: 2px 4px;">${token.text}</mark>`;
  }
}

export { HighlightUfmComponent as api };
```

### Icon Component Example
```typescript
import { UmbUfmComponentBase } from '@umbraco-cms/backoffice/ufm';
import type { UfmToken } from '@umbraco-cms/backoffice/ufm';

// Usage: {@icon-document} renders an Umbraco icon
export class IconUfmComponent extends UmbUfmComponentBase {
  render(token: UfmToken): string | undefined {
    return `<uui-icon name="${token.text}"></uui-icon>`;
  }
}

export { IconUfmComponent as api };
```

## Interface Reference

```typescript
interface ManifestUfmComponent extends ManifestApi<UmbUfmComponentApi> {
  type: 'ufmComponent';
  meta: MetaUfmComponent;
}

interface MetaUfmComponent {
  alias: string;    // Long form: {alias:text}
  marker?: string;  // Short form: {marker text}
}

interface UmbUfmComponentApi extends UmbApi {
  render(token: UfmToken): string | undefined;
}

interface UfmToken {
  text: string;  // The text content after the marker
}
```

## Built-in UFM Components

- `{#key}` or `{umbLocalize:key}` - Localization
- `{=property}` or `{umbValue:property}` - Property values
- `{umbContentName:id}` - Content names
- `{umbLink:url}` - Styled links

## Usage in Markdown

UFM components are used in label descriptions and markdown text:

```json
{
  "type": "propertyEditorUi",
  "meta": {
    "label": "{#myLabel}",
    "description": "Status: {%active} - {!Important note}"
  }
}
```

## Best Practices

- Choose memorable, short markers
- Return safe HTML (escape user input)
- Keep rendering lightweight
- Consider accessibility in output
- When rendering custom elements, use an allowed tag-name prefix: `umb-`,
  `ufm-`, or `uui-`. Other prefixes are removed by UFM's sanitizer.

That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.
````

- Previous: [umbraco-validation-checks](https://syn4pse.dev/terminal/umbraco-validation-checks.md)
- Next: [umbraco-validation-context](https://syn4pse.dev/terminal/umbraco-validation-context.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
