# Blocks

Blocks enable editors to insert structured content elements directly into the Rich Text Editor (RTE). Blocks are [Element Types](/umbraco-cms/fundamentals/data/defining-content/default-document-types.md#element-type) and can be configured with custom properties, styling, and behavior.

Blocks can be added to the Rich Text Editor when:

* Available Blocks are specified as part of the Rich Text Editor Data Type configuration.
* The **Insert Block** toolbar option is enabled in the Rich Text Editor.

![RTE Insert Block Toolbar Button](/files/bb4fJoDIqvSTAPXJOiky)

## Configure Blocks

Blocks are Element Types that must be created before configuring them as blocks in the Rich Text Editor. You can create Element Types in the **Settings** > **Document Types** section

Blocks functionality can then be configured through the Rich Text Editor Data Type configuration as follows.

1. Navigate to **Settings** > **Data Types**.
2. Select your Rich Text Editor Data Type or create a new one.
3. Locate the **Available Blocks** section.
4. Add the Element Types you want to make available as blocks.
5. Configure each Block Type with the options described below.

![RTE Blocks Data Type Configuration](/files/Oq7lclSfrC8T4cjNavkj)

### Editor Appearance

Configure how blocks appear and behave in the Content section:

* **Label** - Define how the block appears in the editor. Umbraco 16 uses [Umbraco Flavoured Markdown](/umbraco-cms/reference/umbraco-flavored-markdown.md) (UFM) syntax for dynamic labels. Use `{=propertyAlias}` to display property values (e.g., `{=author}` for a text property containing the name of an author, or `Written by: {=author}` for a label with static text and dynamic content).
* **Display Inline** - When enabled, blocks remain inline with surrounding text. When disabled, blocks appear on separate lines.
* **Overlay size** - Set the size of the editing overlay when editors work with the block content.

![RTE Blocks Editor Appearance Settings](/files/049GuJj4shmnbaYIVLgU)

### Data Models

Configure the content structure for your blocks:

* **Content model** - The Element Type that defines the main content properties for the block (required).
* **Settings model** - Optional Element Type that defines additional settings or configuration options for the block.

![RTE Blocks Data Models Settings](/files/0KRZubEr7PhNchlxj8IO)

### Catalogue Appearance

Control how blocks appear in the block picker:

* **Background color** - Background color displayed behind the block icon or thumbnail.
* **Icon Color** - Color of the Element Type icon.
* **Thumbnail** - Custom image to replace the default Element Type icon.

## Working with Blocks

### Adding Blocks to Content

Editors can add blocks to rich text content using the **Insert Block** toolbar button:

1. Position the cursor where you want to insert the block
2. Click the **Insert Block** button in the Rich Text Editor toolbar

   ![Adding Blocks to Content - Step 1](/files/idYCAgqTCbXIhgtegyoL)
3. Select the desired Block from the available options

   ![Adding Blocks to Content - Step 2](/files/EXT3UkDE2HkjSHclxXD0)
4. Configure the block content (and settings, if provided)

   ![Adding Blocks to Content - Step 3](/files/9HkDe0trAeILqtLUtMC3)

The block appears in the editor as a structured element.

## Rendering Blocks

To display blocks on the frontend, create Partial Views for each Block.

{% hint style="info" %}
Rich Text Editor blocks use a different view location than Block List blocks. RTE blocks are placed in `Views/Partials/RichText/Components/`, while Block List blocks use `Views/Partials/BlockList/Components/`.
{% endhint %}

### File Structure

* **Location**: `Views/Partials/RichText/Components/`.
* **Naming**: Use the exact Element Type alias as the filename (e.g., `quoteBlock.cshtml` for alias `quoteBlock`).
* **Model**: `Umbraco.Cms.Core.Models.Blocks.RichTextBlockItem`.

The different folder structure ensures that RTE blocks and Block List blocks can have separate rendering implementations, even when using the same Element Types.

{% hint style="warning" %}
The view filename must match the Element Type alias exactly. If you see the error `ArgumentException: ~/Views/Partials/richtext/Components/[filename].cshtml does not match any available view`, verify that your view filename matches your Element Type alias precisely.
{% endhint %}

### Example Partial View

For a Block Type with Element Type alias `quoteBlock`:

```csharp
@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.RichTextBlockItem>

@{
    var quoteText = Model.Content.Value("quoteText")?.ToString();
    var citation = Model.Content.Value("citation")?.ToString();
}

<blockquote class="quote-block">
    @if (!string.IsNullOrEmpty(quoteText))
    {
        <p class="quote-text">@Html.Raw(quoteText)</p>
    }

    @if (!string.IsNullOrEmpty(citation))
    {
        <cite class="quote-citation">@citation</cite>
    }
</blockquote>
```

### Example with Settings Model

For a Call To Action block with Element Type alias `callToActionBlock` and settings model `callToActionBlockSettings`:

```csharp
@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.RichTextBlockItem>
@using Umbraco.Cms.Core.Models

@{
    // Get link from Multi URL Picker
    var linkPicker = Model.Content.Value<IEnumerable<Link>>("link");
    var link = linkPicker?.FirstOrDefault();

    // Get style from settings (if settings model exists)
    var style = "primary"; // Default style
    if (Model.Settings != null)
    {
        var settingsStyle = Model.Settings.Value("style")?.ToString();
        if (!string.IsNullOrEmpty(settingsStyle))
        {
            style = settingsStyle.ToLower();
        }
    }

    // CSS class based on style setting
    var cssClass = $"cta-button cta-button--{style}";
}

@if (link != null && !string.IsNullOrEmpty(link.Url))
{
    <div class="cta-block">
        <a href="@link.Url"
           class="@cssClass"
           @(link.Target == "_blank" ? Html.Raw("target=\"_blank\" rel=\"noopener noreferrer\"") : Html.Raw(""))>
            @(!string.IsNullOrEmpty(link.Name) ? link.Name : "Learn More")
        </a>
    </div>
}
```

### Type-Safe Rendering with Models Builder

When using Models Builder, specify the Content and Settings models for type-safe access:

```csharp
@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.RichTextBlockItem<QuoteBlock, QuoteBlockSettings>>
@using ContentModels = Umbraco.Cms.Web.Common.PublishedModels;

@{
    var style = "";
    if (Model.Settings?.Color != null)
    {
        style = $"style=\"border-left-color: {Model.Settings.Color};\"";
    }
}

<blockquote class="quote-block" @Html.Raw(style)>
    @if (!string.IsNullOrEmpty(Model.Content.QuoteText))
    {
        <p class="quote-text">@Html.Raw(Model.Content.QuoteText)</p>
    }

    @if (!string.IsNullOrEmpty(Model.Content.Citation))
    {
        <cite class="quote-citation">@Model.Content.Citation</cite>
    }
</blockquote>
```

## Build a Custom Backoffice View

Building Custom Views for Block representations in Backoffice is the same for all Block Editors. [Read about building a Custom View for Blocks here](/umbraco-cms/tutorials/creating-custom-views-for-blocklist.md).

## Best Practices

### Content Design

* Design blocks for reusable content patterns.
* Keep block content focused on a single purpose.
* Use descriptive labels that help editors understand the block's function.

### Performance

* Avoid creating too many Blocks - this can overwhelm content editors.
* Use appropriate caching strategies for block rendering.
* Consider the impact of complex blocks on editor performance.

### Accessibility

* Ensure block markup follows accessibility guidelines.
* Provide meaningful labels and descriptions.
* Test block rendering with screen readers.

## Related Articles

* [Element Types](/umbraco-cms/fundamentals/data/defining-content/default-document-types.md#element-type)
* [Rich Text Editor Configuration](/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/configuration.md)
* [Rich Text Editor Extensions](/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/extensions.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.umbraco.com/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/blocks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.