Customize widget appearance (Widget layouts)

Widget layouts is an advanced feature. It lets you change the HTML structure used when a widget type is rendered on your site, using a template override per widget type (for example all Hero widgets).

Who is this for?

  • Users comfortable with HTML and basic templating (the system uses Scriban syntax).
  • Designers or developers who need markup that the default widget does not provide.

If you are not technical, coordinate with someone who can edit templates safely.

Open Widget layouts

  1. Sign in to /admin.
  2. Open Widget layouts in the sidebar (requires Widget layouts permission).

How it works

  1. Select a widget type from the list (Hero, Navigation, Channels list, etc.).
  2. The editor shows a template area. When empty, the site uses the default Razor view from the product.
  3. When you save non-empty content, the site tries to render that widget type using your template and a documented data model (variables such as slides, channels, etc.).
  4. Revert (or clear and save) removes the override and restores the default view.

Reference and preview

  • The screen usually offers sample markup / reference for the selected widget so you know which variables exist.
  • Use preview to test before relying on the template in production.

Safety

  • Broken templates can cause empty output or errors for that widget type; the system may fall back to the default if rendering fails.
  • Keep backups of working templates.
  • Test on a draft page or offline site when possible.

Difference from Branding CSS

  • Branding → custom CSS — styles the existing HTML.
  • Widget layouts — changes the HTML (and can include inline logic loops).

Related articles