Nunjucks tutorial — Lily Design System

Wetin you go build

Small server-rendered contact form — input wey get label, submit button, zero JavaScript payload — first bare, then styled, for about 10 minutes.

Before you start

You need git, Node 22 or newer, and pnpm 10 or newer. Any Nunjucks pipeline dey work — Eleventy, Express, or plain Nunjucks.

Step 1 — Get di code

git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-nunjucks-headless
pnpm install
pnpm test        # vitest rendering every macro

Each component na directory inside components/ wey get macro.njk, im test, and im docs — for example components/button/macro.njk. Point your Nunjucks loader to components/ (for Eleventy, add am to di includes path) and import wetin you need.

Step 2 — Your first component

{% from "components/button/macro.njk" import button %}

{{ button({ text: "Save", type: "submit" }) }}

E dey render <button class="button" type="submit">Save</button>. Macros dey take single params object: text (escaped) or html (raw), type, label for aria-label, and class hook appender.

Step 3 — Compose small form

{% from "components/form/macro.njk" import form %}
{% from "components/label/macro.njk" import label %}
{% from "components/text-input/macro.njk" import textInput %}
{% from "components/button/macro.njk" import button %}

<form class="form" method="post">
  <div class="field">
    {{ label({ for: "name", text: "Full name" }) }}
    {{ textInput({ id: "name", name: "name", required: true }) }}
  </div>
  {{ button({ text: "Save", type: "submit" }) }}
</form>

Because everything dey render for di server, di browser go receive pure semantic HTML with di class hooks — JavaScript payload of zero bytes.

Check your work: load di page and di form go look plain — exactly as dem plan am: di styling still dey come. Press Tab: focus go move through every control, di label go dey announced, and submit dey work. Di behaviour don finish; di look na yours and e be next.

Step 4 — Style am

Style di hooks — .button, .text-input, .label, .field — inside your stylesheet, or link ready-made theme inside your base layout:

<link rel="stylesheet" href="/themes/united-kingdom-government-digital-service.css" />

Step 5 — See everything dey work

Di Nunjucks + Eleventy example app dey build di full catalog as static site with per-component demo pages:

git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-nunjucks-eleventy-examples
pnpm install && pnpm run dev

Next steps

Theming — including di Eleventy cookie pattern for flash-free SSR theme switching.
Preference helpers — language and text size.
Component catalog — props, ARIA, and keyboard for each component.

You get questions as you dey go? Di help page full of answers — and if any step fit clearer, tell us and we go gladly improve di tutorial.