Hooks are a mechanism that lets developers inject code and content into specific, predefined points of a Salla storefront — without modifying the core theme files. Think of them as designated slots that are already built into the system, waiting to be used.Whether you are building a theme or an app, hooks are the correct and supported way to extend Salla storefronts. They keep your customizations isolated from the core, which means theme updates will never overwrite your work, and your code will never break what already works.Hooks are not a shortcut or a workaround — they are the official extensibility layer of the Salla Twilight theme. Both theme developers and app developers are expected to understand and use them.
How Hooks Work#
At its core, a hook is a named point in the system. When that point is reached — either during page rendering or at runtime in the browser — the system calls whatever has been registered to that hook.The entire hooks system is powered by a single Hooks class inside Twilight. It manages two things:Template slots — named points in Twig templates where content can be injected at render time
Component hooks — named events on web components that can be listened to at runtime via JavaScript
The Two Surfaces#
Template slots are hooks embedded inside
.twig files using Twig syntax. When the page is rendered on the server, Twilight processes these tags and injects any content registered to that slot.
These hooks cover every major area of every page — the <head>, body, product pages, cart, thank you page, customer pages, and more.
Who Uses Hooks and How#
Hooks are used by both theme developers and app developers. The surface they interact with is different, but the underlying concept is exactly the same. | Theme Developer | App Developer |
|---|
| What they use | Template slots in .twig files | JavaScript API via Salla.hooks |
| When it runs | Server-side, at page render time | Client-side, at runtime in the browser |
| What they inject | HTML, components, scripts | Callbacks and logic |
| Entry point | {% hook 'hook.name' %} | Salla.hooks.registerHook(...) |
Neither developer needs to modify core files. Neither developer needs to worry about conflicts. The hooks system handles isolation, ordering, and error containment for both.
Key Principles#
Predefined — register to them, not create them
You do not define where a hook fires. Salla defines that. Your job is to register your code or content to an existing hook name. If a hook does not exist for what you need, you can request one — see Requesting New Hooks below.
Timing-Safe
For component hooks, it does not matter when your script loads. The system keeps a history of all components that have already loaded, and your callback will be called for them immediately upon registration. You will never miss a component due to a race condition.
Isolated
Errors in your hook callback do not crash the core system. The hooks system catches errors from registered callbacks and logs them to the console without breaking anything else on the page.
Whitelisted
For component hooks, only approved tag and hook name combinations can be registered. Attempting to register an unlisted hook will be silently blocked with a console warning. This prevents misuse and keeps the system predictable.
Requesting New Hooks#
The hooks whitelist is maintained by the Salla engineering team. If you need access to a component or page area that does not have a hook yet, you can request one via email.
Where to Go From Here#
Now that you understand what hooks are and how the system works, go to the article that matches what you are building:| I am building... | Go to... |
|---|
| A Salla theme | Template Hooks — full list of available slots across every page, with Twig syntax and examples |
| An app or partner integration | Component Hooks — full JavaScript API reference, available components, and real-world examples |
