> For the complete documentation index, see [llms.txt](https://docs.rafflex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rafflex.io/advanced/twig-templating/header-and-footer-variables.md).

# Header and Footer Variables

The variables available in custom header and footer Twig templates, including the logged in customer, their site credit balance, the basket, links to key pages, categories and recent instant winners.

Custom header and footer templates let your site's navigation and footer be completely bespoke while still showing live information, such as the customer's site credit balance or the number of tickets in their basket.

{% hint style="info" %}
**Custom headers and footers are set up by the RaffleX team.** If you would like one, contact support with a description or design of what you want. You can also use this page (with an AI assistant, if you like) to draft the template yourself and send it over.
{% endhint %}

This page lists everything a custom header or footer can show. These variables only work in custom headers and footers. Page builder blocks, such as the [Custom Twig Block](/advanced/twig-templating/custom-twig-block.md), have their own variables.

***

### Usage

A simple account menu that greets the customer, shows their balance and links to useful pages:

```twig
<nav class="account-menu">
  {% if is_logged_in %}
    <span>Hi {{ user.name }}</span>
    <a id="wallet" href="{{ urls.account_wallet }}">Site credit: {{ wallet_balance }}</a>
    <a href="{{ urls.account_tickets }}">My tickets</a>
    <a href="{{ urls.account_wins }}">My wins</a>
    <a href="{{ urls.playsafe }}">Safe Play</a>
    <a href="{{ urls.logout }}">Log out</a>
  {% else %}
    <a href="{{ urls.login }}">Log in</a>
    <a href="{{ urls.register }}">Sign up</a>
  {% endif %}
  <a href="{{ urls.basket }}">Basket ({{ cart_count }})</a>
</nav>
```

***

### Customer

| Variable         | Type   | What it holds                                                                                         | Example  |
| ---------------- | ------ | ----------------------------------------------------------------------------------------------------- | -------- |
| `is_logged_in`   | yes/no | Whether the visitor is logged in                                                                      | true     |
| `wallet_balance` | text   | The customer's site credit balance with the currency symbol. Empty for visitors who are not logged in | "£25.00" |
| `user`           | object | The current customer. Visitors who are not logged in get a guest version (see below)                  |          |

**The `user` object:**

| Variable            | What it holds                                                                      | Example             |
| ------------------- | ---------------------------------------------------------------------------------- | ------------------- |
| `user.id`           | The customer's account number                                                      | 1042                |
| `user.name`         | First name                                                                         | "Sam"               |
| `user.last_name`    | Surname                                                                            | "Taylor"            |
| `user.full_name`    | First name and surname together                                                    | "Sam Taylor"        |
| `user.display_name` | The public display name the customer has chosen. "Guest" when not logged in        | "SamT"              |
| `user.email`        | Email address                                                                      | "<sam@example.com>" |
| `user.is_logged_in` | Same as `is_logged_in`                                                             | true                |
| `user.balance`      | Site credit balance with the currency symbol (the same figure as `wallet_balance`) | "£25.00"            |
| `user.balance_raw`  | Site credit balance as a plain number, for comparisons                             | 25                  |

For guests, every field is empty apart from `display_name` ("Guest"), `is_logged_in` (false) and `balance_raw` (0).

{% hint style="info" %}
Not every customer sets a display name. For a friendly greeting, `user.name` (first name) is the safest choice, or use a fallback: `{{ user.display_name|default(user.name) }}`.
{% endhint %}

{% hint style="warning" %}
**Give the balance link `id="wallet"`.** Your site uses this to hide the balance on the order confirmation page, so a customer cannot see an instant win prize land in their balance before they have played their instant win games. Without it, the surprise can be spoilt. The example in [Usage](#usage) shows where it goes.
{% endhint %}

***

### Basket

| Variable            | Type   | What it holds                                                       | Example  |
| ------------------- | ------ | ------------------------------------------------------------------- | -------- |
| `cart_count`        | number | The total number of tickets in the basket                           | 12       |
| `cart.item_count`   | number | Same as `cart_count`                                                | 12       |
| `cart.unique_items` | number | How many different competitions are in the basket                   | 3        |
| `cart.subtotal`     | text   | The basket total before basket wide discounts, such as a coupon     | "£24.00" |
| `cart.subtotal_raw` | number | The subtotal as a plain number                                      | 24       |
| `cart.total`        | text   | The basket total after all discounts                                | "£20.00" |
| `cart.total_raw`    | number | The total as a plain number                                         | 20       |
| `cart.has_discount` | yes/no | Whether a discount is reducing the total                            | true     |
| `cart.is_empty`     | yes/no | Whether the basket is empty                                         | false    |
| `cart.items`        | list   | One entry per competition in the basket (see below)                 |          |
| `cart.conditions`   | list   | Discounts applied to the whole basket, such as a coupon (see below) |          |

**Each entry in `cart.items`:**

| Variable                      | What it holds                                                                                                    | Example        |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------- |
| `item.id`                     | The competition's ID                                                                                             | 123            |
| `item.name`                   | The competition's title                                                                                          | "Win a BMW M3" |
| `item.price`                  | The price per ticket, after any discount on this line                                                            | "£1.99"        |
| `item.price_raw`              | The price per ticket as a plain number                                                                           | 1.99           |
| `item.quantity`               | How many tickets for this competition                                                                            | 10             |
| `item.line_total`             | The total for this line                                                                                          | "£19.90"       |
| `item.line_total_raw`         | The line total as a plain number                                                                                 | 19.9           |
| `item.image`                  | The competition image address                                                                                    | Full address   |
| `item.slug`                   | The last part of the competition's web address                                                                   | "win-a-bmw-m3" |
| `item.url`                    | The full web address of the competition page                                                                     | Full address   |
| `item.has_discount`           | Whether a discount applies to this line                                                                          | false          |
| `item.discount_name`          | The name of that discount, or empty                                                                              |                |
| `item.original_price`         | The price per ticket before that discount, or empty                                                              |                |
| `item.promotion.free_tickets` | Bonus free tickets from a promotion such as Buy One Get One Free (`item.promotion` is empty when there are none) | 5              |

**Each entry in `cart.conditions`:**

| Variable                | What it holds                                                                                   | Example       |
| ----------------------- | ----------------------------------------------------------------------------------------------- | ------------- |
| `condition.name`        | The name of the discount. For a coupon, this is the **Title** you gave the coupon, not its code | "Summer Sale" |
| `condition.type`        | The kind of adjustment. Coupons show as "discount"                                              | "discount"    |
| `condition.value`       | The discount as set up: a percentage such as "-10%", or a fixed amount such as "-5"             | "-10%"        |
| `condition.savings`     | How much it saves, with the currency symbol                                                     | "£2.40"       |
| `condition.savings_raw` | The saving as a plain number                                                                    | 2.4           |

A small basket preview:

```twig
{% if cart.is_empty %}
  <p>Your basket is empty.</p>
{% else %}
  <ul>
    {% for item in cart.items %}
      <li>
        <a href="{{ item.url }}">{{ item.name }}</a>
        x{{ item.quantity }}: {{ item.line_total }}
        {% if item.promotion %}(+{{ item.promotion.free_tickets }} free){% endif %}
      </li>
    {% endfor %}
  </ul>
  {% for condition in cart.conditions %}
    <p>{{ condition.name }}: you save {{ condition.savings }}</p>
  {% endfor %}
  <p>Total: {{ cart.total }}</p>
  <a href="{{ urls.basket }}">Go to basket</a>
{% endif %}
```

#### A live basket count

The basket values above are filled in when the page loads. When a customer adds tickets without leaving the page (for example with Quick Add), the page is not reloaded, so those values do not change. For a basket count that updates by itself, use the `raffleBasket` component:

```twig
<div x-data="raffleBasket({ initialCount: {{ cart_count }} })">
  <a href="{{ urls.basket }}">
    Basket
    <span x-show="hasItems" x-cloak x-text="count"></span>
  </a>
</div>
```

| Setting or value     | What it does                                                                                                                                                                                                                    |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `initialCount`       | The count to start with. Always pass `{{ cart_count }}`                                                                                                                                                                         |
| `dismissAfter`       | How long the "just added" details stay before clearing, in milliseconds. Defaults to 5000 (5 seconds). Set 0 to keep them until dismissed                                                                                       |
| `count`              | The live number of tickets in the basket                                                                                                                                                                                        |
| `hasItems`           | True when the basket is not empty                                                                                                                                                                                               |
| `lastAdded`          | Details of the tickets just added, or empty. `title` is a short message such as "x10 Added To Cart", `content` is the competition's title, `image` is its image, `link` is the basket address and `tickets` is the number added |
| `dismissLastAdded()` | Clears `lastAdded` straight away                                                                                                                                                                                                |

`lastAdded` is filled in when a customer adds tickets on a competition page. Quick Add buttons update `count` but do not fill in `lastAdded`, because they show their own message.

You can use `lastAdded` to show a small "added to basket" pop up in your header:

```twig
<div x-data="raffleBasket({ initialCount: {{ cart_count }}, dismissAfter: 4000 })">
  <a href="{{ urls.basket }}">Basket <span x-text="count"></span></a>

  <div x-show="lastAdded" x-cloak x-transition.opacity @click="dismissLastAdded()" class="added-popup">
    <img x-show="lastAdded?.image" :src="lastAdded?.image" alt="">
    <span x-text="lastAdded?.title"></span>
    <span x-text="lastAdded?.content"></span>
  </div>
</div>
```

***

### Links

Every `urls` value is the full web address of the page on your site, so it always points to the right place, even if your domain changes.

| Variable                | Page                                                                                                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `urls.home`             | Homepage                                                                                                                                                            |
| `urls.results`          | Results                                                                                                                                                             |
| `urls.completed`        | Completed competitions                                                                                                                                              |
| `urls.entry_lists`      | Entry lists                                                                                                                                                         |
| `urls.instant_winners`  | Instant winners list. Only link to it when `instant_winner_list_enabled` is true (see [Instant winners](#instant-winners))                                          |
| `urls.about`            | About                                                                                                                                                               |
| `urls.contact`          | Contact (with your contact form)                                                                                                                                    |
| `urls.privacy`          | Privacy policy                                                                                                                                                      |
| `urls.terms`            | Terms and conditions                                                                                                                                                |
| `urls.basket`           | Basket                                                                                                                                                              |
| `urls.login`            | Log in                                                                                                                                                              |
| `urls.register`         | Sign up                                                                                                                                                             |
| `urls.forgot_password`  | Forgotten password                                                                                                                                                  |
| `urls.logout`           | Log out. A normal link works, nothing else is needed                                                                                                                |
| `urls.account_settings` | The customer's account settings                                                                                                                                     |
| `urls.account_tickets`  | The customer's tickets                                                                                                                                              |
| `urls.account_orders`   | The customer's orders                                                                                                                                               |
| `urls.account_wins`     | The customer's wins (every prize they have won)                                                                                                                     |
| `urls.account_wallet`   | The customer's wallet, with their site credit balance and history                                                                                                   |
| `urls.account_payout`   | The customer's **Payouts** page, where they save the bank details used for withdrawals. See [Wallet and Withdrawals](/essential-settings/wallet-and-withdrawals.md) |
| `urls.playsafe`         | The customer's **Play Safe** page. See [Safe Play Setting](/additional-settings/safe-play-setting.md)                                                               |

{% hint style="info" %}
The account links (`account_...`, `playsafe` and `logout`) only work for logged in customers. Anyone else is sent to the log in page. Show them inside an `is_logged_in` check, as in the [Usage](#usage) example.
{% endhint %}

***

### Categories and Pages

| Variable              | Type | What it holds                                                                                                                          |
| --------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `categories`          | list | Your [product categories](/create-your-first-raffle/product-categories.md) that currently have competitions. Each has `name` and `url` |
| `pages.menu_links`    | list | Your active pages, for a menu. Each has `title` and `url` (see below)                                                                  |
| `pages.results_title` | text | The title of your Results page (or "Results" if none is set)                                                                           |
| `pages.about_title`   | text | The title of your About page (or "About" if none is set)                                                                               |

**What is in `pages.menu_links`:** every page that is switched on, apart from your homepage, About, Privacy Policy and Terms. That includes the custom pages you have made, and also your **Contact** and **Results** pages. It is the same list the standard footer shows under **Page Links**. See [Manage Your Pages](/customise-your-site/manage-your-pages.md).

{% hint style="info" %}
For **Contact** and **Results**, link with `urls.contact` and `urls.results` instead, which open the full Contact page (with your contact form) and your Results page. The example below leaves those two out of the menu loop and adds them separately.
{% endhint %}

```twig
{% for link in pages.menu_links %}
  {% if not (link.url ends with '/contact' or link.url ends with '/results') %}
    <a href="{{ link.url }}">{{ link.title }}</a>
  {% endif %}
{% endfor %}
<a href="{{ urls.results }}">{{ pages.results_title }}</a>
<a href="{{ urls.contact }}">Contact</a>
```

A category menu:

```twig
<ul>
  {% for category in categories %}
    <li><a href="{{ category.url }}">{{ category.name }}</a></li>
  {% endfor %}
</ul>
```

Using your own wording for the About and Results links:

```twig
<a href="{{ urls.results }}">{{ pages.results_title }}</a>
<a href="{{ urls.about }}">{{ pages.about_title }}</a>
```

{% hint style="info" %}
New categories and pages can take up to a couple of hours to appear in a custom header or footer. If you need one to show sooner, contact Rafflex support.
{% endhint %}

***

### Instant Winners

| Variable                      | Type   | What it holds                                                                   |
| ----------------------------- | ------ | ------------------------------------------------------------------------------- |
| `instant_winner_list_enabled` | yes/no | Whether **Enable Instant Winner List** is switched on in your General settings  |
| `instant_wins_today`          | number | How many instant wins there have been so far today. Refreshes every few minutes |
| `instant_winners`             | list   | Up to 10 of the most recent instant winners from the last 30 days (see below)   |

**Each entry in `instant_winners`:**

| Variable                 | What it holds                                                               | Example           |
| ------------------------ | --------------------------------------------------------------------------- | ----------------- |
| `winner.winner_name`     | The winner's name, shown the way your **Winners Name Display** setting says | "Sam T"           |
| `winner.prize`           | The prize description                                                       | "£50 Site Credit" |
| `winner.prize_value`     | The prize value without a currency symbol, or empty                         | "50.00"           |
| `winner.prize_value_raw` | The prize value as a plain number, or empty                                 | 50                |
| `winner.is_site_credit`  | Whether the prize is site credit                                            | true              |
| `winner.product_title`   | The competition it was won in                                               | "Win a BMW M3"    |
| `winner.product_url`     | The full web address of that competition                                    | Full address      |
| `winner.product_image`   | That competition's image address                                            | Full address      |
| `winner.date`            | The date it was won                                                         | "Feb 12, 2026"    |
| `winner.date_ago`        | How long ago it was won                                                     | "2 hours ago"     |

The list leaves out prizes from [hidden VIP competitions](/create-your-first-raffle/hidden-vip-competitions.md) and follows your **Minimum Site Credit Shown On Instant Winner List** setting, so small prizes can be kept off it. That setting and **Enable Instant Winner List** are explained in [General Settings](/additional-settings/settings/general-settings.md). **Winners Name Display** is explained in [User Experience Settings](/additional-settings/settings/user-experience-settings.md). To add the currency symbol to `prize_value`, use `{{ settings.currency_icon }}{{ winner.prize_value }}`.

{% hint style="warning" %}
`instant_winners` and `instant_wins_today` are filled in even when your instant winner list is switched off. Wrap anything about instant winners in an `instant_winner_list_enabled` check, as below, so it only shows when you want it to.
{% endhint %}

```twig
{% if instant_winner_list_enabled %}
  <a href="{{ urls.instant_winners }}">Instant Winners</a>

  {% if instant_wins_today > 0 %}
    <span class="badge">{{ instant_wins_today }} winners today!</span>
  {% endif %}

  {% if instant_winners|length > 0 %}
    <div class="ticker">
      {% for winner in instant_winners %}
        <span>{{ winner.winner_name }} won {{ winner.prize }}</span>
      {% endfor %}
    </div>
  {% endif %}
{% endif %}
```

***

### Everything Else

| Variable   | What it holds                                                                                                                             |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `settings` | Your site name, colours, logos, social links and review scores. See [Settings Variables](/advanced/twig-templating/settings-variables.md) |
| `year`     | The current year, handy for a copyright line (for example "2026")                                                                         |

A copyright line for your footer:

```twig
<p>&copy; {{ year }} {{ settings.site_name }}. {{ settings.footer_text }}</p>
```

***

### Design notes

If you are drafting a template to send to the Rafflex team, these points will help it work first time:

* **The header is your whole header, on every screen size.** There is no separate mobile menu, so include a menu that works on phones (for example a button that opens a full screen list of links).
* **The header stays at the top of the screen** as visitors scroll, on a dark background. Use light coloured text.
* **Write your styles in a `<style>` tag** with plain CSS. Avoid utility class frameworks such as Tailwind classes, because they can clash with your site's own styles.
* **Use your brand colours** through CSS custom properties, for example `style="--primary: {{ settings.primary_color }}; --btn-text: {{ settings.button_text_color }};"` on the outer wrapper, then `var(--primary)` in your CSS. Make the outer wrapper `width: 100%`.
* **Keep the important links:** your basket, log in or account links, Terms and conditions, Privacy policy and Safe Play.
* **Give the balance link `id="wallet"`** (see [Customer](#customer)).
* **Every footer must end with the "Powered by RaffleX" line.** Leave room for it at the very bottom of your design. It cannot be removed or hidden.
* **Simple interactive touches**, such as dropdown menus, can be built with Alpine attributes like `x-data`, `x-show` and `@click`.

***

### AI Context

**For AI Assistants:** This documents the variables available in Rafflex custom header and footer (layout) Twig templates. These templates are installed by the Rafflex team. Page builder blocks do not receive these variables.

**Context variables:**

* `is_logged_in` (boolean), `wallet_balance` (formatted site credit, empty string for guests)
* `user`: id, name, last\_name, full\_name, display\_name ("Guest" for guests, may be empty for customers who have not chosen one), email, is\_logged\_in, balance (formatted), balance\_raw
* `cart_count` (total tickets), `cart`: items, item\_count, unique\_items, subtotal, subtotal\_raw, total, total\_raw, has\_discount, conditions, is\_empty. Each item: id, name, price, price\_raw, quantity, image, slug, url, line\_total, line\_total\_raw, has\_discount, discount\_name, original\_price, promotion (null or an object with free\_tickets). Each condition: name (coupon title, not code), type ("discount" for coupons), value ("-10%" or "-5"), savings, savings\_raw.
* `urls` (absolute): home, results, completed, entry\_lists, instant\_winners, about, contact, privacy, terms, basket, login, register, forgot\_password, logout (plain link), account\_settings, account\_tickets, account\_orders, account\_wins, account\_wallet, account\_payout, playsafe. Account links require login.
* `categories`: list of name and url for categories that have competitions.
* `pages`: menu\_links (list of title and url for active pages except home, about, privacy and terms; includes contact and results, which should instead be linked with urls.contact and urls.results), results\_title, about\_title.
* `instant_winner_list_enabled` (boolean), `instant_wins_today` (number), `instant_winners` (up to 10 from the last 30 days, filled even when the list is disabled): winner\_name, prize, prize\_value (no currency symbol), prize\_value\_raw, is\_site\_credit, product\_title, product\_url, product\_image, date, date\_ago.
* `settings` (see Settings Variables), `year`.

**Twig:** tags `if`, `for`, `set`. Filters `upper`, `lower`, `date`, `number_format`, `default`, `length`, `first`, `last`, `join`, `slice`, `round`, `trim`, `escape`. Operators such as `ends with` and `in` work.

**Key notes:**

1. Balances are pre formatted with the currency symbol and are empty strings for guests. Do not prepend `settings.currency_icon` to them.
2. Always put `id="wallet"` on the site credit balance link.
3. `urls` values are full absolute URLs.
4. Use `raffleBasket({ initialCount: {{ cart_count }} })` for a live basket count. Properties: count, hasItems, lastAdded (title is a message such as "x10 Added To Cart", content is the competition title, image, link to the basket, tickets; filled by competition page adds, not by raffleQuickAdd), method dismissLastAdded(), option dismissAfter (milliseconds, default 5000, 0 disables).
5. Guard instant winner content with `instant_winner_list_enabled`.
6. The header must include its own mobile navigation (Alpine.js), use plain CSS in a `<style>` tag rather than Tailwind classes, and use a full width outer wrapper with `--primary` and `--btn-text` custom properties.
7. Examples are for context only. Always follow the site owner's design directions.