Hooks Components - Twilight Documentation

Component Hooks are a JavaScript API that lets app and partner developers safely interact with Salla's web components at runtime. You can hook into a component when it loads, intercept its validation flow, modify its UI, or rewrite a request URL — all from your own script, with no timing worries.

Component Hooks use JavaScript and are meant for app and partner developers. If you are a theme developer looking to inject content into page templates via Twig, see the Template Hooks article instead.

📙 What You'll Learn

How It Works

Registering a Hook

Available Components & Hooks

Late Registration Support

Hook Options: Priority & Once

Removing a Hook

Component Properties Reference

Real-World Use Cases

Security: The Whitelist System

How It Works

The hooks system is exposed globally via Salla.hooks and is built around three internal structures:

Store — a Map of registered callbacks, keyed by component tag and hook name.

Whitelist — a Map that defines exactly which hook names are allowed per component tag.

Component History — a Map that records every component element that has loaded on the page, enabling late registration.

When a Salla component mounts on the page, it calls Salla.hooks.registerComponent(tag, element) internally. This fires any already-registered componentDidLoad callbacks for that element and adds it to the history — so any future registrations can also reach it retroactively.

Always wrap your hook registrations inside Salla.onReady() to guarantee the Salla SDK is fully initialized before your code runs.

Registering a Hook

Parameter	Type	Required	Description
`tag`	`string`	✅	The component tag name (e.g. `'salla-add-product-button'`)
`hookName`	`string`	✅	The hook to subscribe to (e.g. `'componentDidLoad'`, `'validate'`)
`callback`	`Function`	✅	Runs when the hook fires. Receives a context argument depending on the hook.
`options`	`object`	❌	`{ priority: number, once: boolean }` — both optional

Returns: An unsubscribe function. Call it to cleanly remove your hook.

Available Components & Hooks

`salla-add-product-button`

Hook Name	When Called	Context Received	What You Can Modify
`componentDidLoad`	When the button component finishes rendering	`element` (HTMLElement)	The element and its children
`validate`	During the add-to-cart validation flow	`{ isValid, productId, component }`	`ctx.isValid` to block or allow the action

`salla-products-list`

Hook Name	When Called	Context Received	What You Can Modify
`componentDidLoad`	When the list component finishes rendering	`element` (HTMLElement)	The element and its children
`beforeBuildListUrl`	Before the product fetch URL is built or pagination cursor is consumed	`{ component, url }`	`ctx.url` to rewrite the request URL

Other Whitelisted Components

The following components currently support componentDidLoad only:

Component Tag	Description
`salla-product-options`	Product options selector
`salla-products-slider`	Horizontal product slider
`salla-hook`	Internal theme slot mounting component
`salla-scopes`	Scopes / permissions component
`salla-user-menu`	User account menu

NOTE

New components and hook names are added with each Twilight release. If you need a hook that isn't listed here, see Requesting New Hooks in the Overview article.

Late Registration Support

This is one of the most powerful aspects of the system. Your script does not need to load before the components.

The Problem

In a classic event-driven model, if a component fires its load event before your script is ready, you miss it entirely. This forces brittle load-order dependencies that are hard to maintain.

The Solution

The hooks system keeps a component history. When you register a componentDidLoad hook, it immediately invokes your callback for every component of that type that has already loaded, then continues firing for future ones.

Here is exactly what happens under the hood:

Component Loads

A salla-add-product-button element renders on the page. It internally calls registerComponent(), fires any already-registered componentDidLoad callbacks, and adds itself to the component history.

Your Script Loads Later

Your partner script loads — after the component — and calls Salla.hooks.registerHook('salla-add-product-button', 'componentDidLoad', cb).

Immediate Catchup

The system checks the component history and immediately calls your callback for every existing salla-add-product-button element on the page.

Future Components Covered Too

Any new salla-add-product-button elements that load after your registration will also trigger your callback normally going forward.

Hook Options: Priority & Once

The optional fourth argument to registerHook() accepts two options.

priority

once

Removing a Hook

You have three ways to remove hooks depending on how granular you need to be.

Unsubscribe Function

removeHook()

clear()

The cleanest approach — store the return value of registerHook() and call it when done.

Component Properties Reference

When your callback receives a component object — either directly as element in componentDidLoad or via ctx.component in validate — you have access to the full component instance.

The following properties are available on salla-add-product-button:

Context objects are passed by reference. Modifying ctx.isValid in the validate hook directly affects whether the add-to-cart action proceeds. Be deliberate about what you change.

Real-World Use Cases

Use Case 1: Subscription Products — Modify UI and Block Re-Purchase

Use Case 2: Booking Permission Check

Use Case 3: Quick Button Text Change

Use Case 4: Rewrite the Products List Fetch URL

Security: The Whitelist System

Every call to registerHook() is validated against the whitelist before any callback is stored. Two checks must pass:

Is the tag in the whitelist?

Is the hook name allowed for that tag?

If either check fails, the registration is silently ignored and a warning is printed to the browser console. A no-op function is returned instead of a real unsubscribe handle — so your code won't break, but the hook won't do anything.

✅ Valid Usage

❌ Blocked Usage

INFO

To register a new component tag or hook name, edit the _whitelist Map in /packages/twilight/src/lib/hooks.js. See Requesting New Hooks in the Overview article for the full process.

Where to Go From Here

Next Step	Description
Hooks Overview	Go back to understand how Template and Component Hooks connect
Template Hooks	Explore server-side Twig hooks for theme developers

Component Hooks

📙 What You'll Learn#

How It Works#

Registering a Hook#

Available Components & Hooks#

salla-add-product-button#

salla-products-list#

Other Whitelisted Components#

Late Registration Support#

The Problem#

The Solution#

Hook Options: Priority & Once#

Removing a Hook#

Component Properties Reference#

Real-World Use Cases#

Security: The Whitelist System#

Where to Go From Here#

📙 What You'll Learn

How It Works

Registering a Hook

Available Components & Hooks

`salla-add-product-button`

`salla-products-list`

Other Whitelisted Components

Late Registration Support

The Problem

The Solution

Hook Options: Priority & Once

Removing a Hook

Component Properties Reference

Real-World Use Cases

Security: The Whitelist System

Where to Go From Here