Mastering Pug Mixins: Reusable Components for Templates

Define a reusable fragment once with mixin and call it with +mixinName to avoid repeating markup. Mixins accept parameters and can yield a block of inner content via the block keyword, which is replaced at render time.

Mechanism with a worked alert mixin

The mixin below accepts a type and an optional title and wraps any nested markup in an alert container.

mixin alert(type, title = 'Notification')
  div(class='alert alert-' + type)
    h4 #{title}
    div.content
      block

+alert('warning', 'Note')
  | This is a warning with inline text.

+alert('success')
  p Your changes have been saved successfully.

When compiled, each +alert call expands to a div with the appropriate classes, the title, and the block content inserted where block appears.

Limits and common mistakes

• Missing block content: If the mixin uses block and the call provides no indented content, the output is empty. Provide content via a pipe | or nested tags with correct indentation.
• Name collisions: Defining two mixins with the same name in one file silently overwrites the first. Keep names unique and check import order.
• Template-time only: Mixins are compiled by Pug, not callable as JavaScript functions outside the template scope.

Practical verification

Render locally with the Pug CLI and inspect the HTML. Run pug template.pug -o out then check that classes and nested content appear as expected and that the markup validates.