Create a new widget

In Igloo 17, widgets are blocks in the Block Grid. Creating a new widget means creating a couple of element types, registering them as a block on Igloo's Block Grid data type, and adding a Razor view to render it.

In this example we'll build a simple Hello World widget with an editable heading, that inherits Igloo's shared settings (palette, anchor id, custom CSS classes) so it themes like every other block.

v13 → v17 change

Igloo 17 uses Umbraco's Block Grid (not the old Block List). Block views now live under Views/Partials/blockgrid/Components/ and inherit UmbracoViewPage<BlockGridItem<TContent, TSettings>> instead of the old UmbracoViewPage<BlockListItem>. If you're porting an old widget, recreate it as a Block Grid block following the steps below.

1. Create the element types

A widget is made of two element types — one for the content the editor fills in, and one for its settings.

In the Umbraco backoffice go to Settings → Document Types and create two Document Types that are marked as element types (toggle Is an Element Type). Creating Document Types and element types is standard Umbraco — see Defining Content and Compositions.

1. Hello World — the content. Add a Heading property (Textstring).
2. Hello World Settings — the settings. Add the Base Block Settings composition (Compositions… → Base Block Settings).

Inherit the shared settings via the composition

Adding the Base Block Settings composition gives your widget the common settings every block shares — Alias, Anchor Id, Custom CSS Classes and Palette — and is what lets <igloo-block-wrap> (step 4) apply the selected palette and styling automatically. Add any widget‑specific settings (e.g. a text alignment) to this element type as well.

2. Register the block on the Block Grid

Open Settings → Data Types → Igloo → Igloo - Content - Block Grid and add a new block:

1. Click Add block and pick the Hello World content element type.
2. Open the block and set its Settings model to Hello World Settings.
3. Choose the allowed column spans, the group it appears under in the block picker (Blocks / Full Width), and any areas — see column span.

Configuring blocks, column spans, areas and groups is standard Umbraco Block Grid configuration — see the Block Grid property editor documentation.

3. Create the render view

Igloo renders Block Grid blocks using Umbraco's default convention: a partial view per block, named after the content element type alias, in Views/Partials/blockgrid/Components/.

Create Views/Partials/blockgrid/Components/helloWorld.cshtml:

@inherits UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.BlockGridItem<ContentModels.HelloWorld, ContentModels.HelloWorldSettings>>
@{
    var content = Model.Content;
    var settings = Model.Settings;
}

<igloo-block-wrap settings="settings" content="content" class="text-center">
    <h1>@content.Heading</h1>
</igloo-block-wrap>

The strongly-typed ContentModels.HelloWorld / HelloWorldSettings come from ModelsBuilder. The view location and BlockGridItem<TContent, TSettings> model are the standard Umbraco approach for rendering the Block Grid.

4. Wrap the output in <igloo-block-wrap>

<igloo-block-wrap> is an Igloo tag helper that renders the block's outer element and applies everything that comes from the shared settings, so your widget looks and behaves like the built-in ones. Given the settings and content, it outputs a wrapper with:

• the block's alias and a component class (for consistent spacing),
• any Custom CSS Classes,
• the selected Palette (a palette-{key} class, plus a dark class when the palette background is dark),
• the Anchor Id as the element id,
• any extra attributes/classes you pass (e.g. class="text-center").

Igloo-specific

<igloo-block-wrap> binds its settings to ICompBaseBlockSettings, which is why the settings element type must include the Base Block Settings composition (step 1). The tag helper is registered for you via @addTagHelper *, Igloo in Igloo's view imports.

Other Igloo tag helpers and helpers you can reuse in a widget view:

Helper	Use
<igloo-heading heading="@content.Heading" />	Render an Igloo Heading property with its chosen heading level.
<igloo-button-list model="@content.Buttons" />	Render a list of Igloo buttons.
BlockHelper.GetTextAlignment(settings?.TextAlignment)	Map an alignment setting to its CSS class.

Also take a look at the views to see how they work on our Github

How it renders on the page

You don't need to wire anything else up — the page template renders the whole grid with Umbraco's standard helper, which resolves each block to the matching view in blockgrid/Components/ by alias:

@await Html.GetBlockGridHtmlAsync(Model, "content")

Publish a page, add your Hello World block from the block picker, and it will render through helloWorld.cshtml.

Learn from the built-in blocks

Every built-in widget is a view in Views/Partials/blockgrid/Components/ (e.g. textBlock.cshtml, headerBlock.cshtml, podBlock.cshtml). They're the best reference for patterns like rich text output, buttons, media and areas. You can also override a built-in block's markup by placing a view with the same name in your own site's Views/Partials/blockgrid/Components/ folder.