Slots overview

Read this page when you want to add content to a page without forking the component that renders it, or when you need to know which slots exist.

A slot is a named spot in the markup, written <HookSlot name="header:start" />. Anything registered under that name appears there: your theme code, the engine's own defaults, and apps installed on the store. If nothing is registered, the slot renders nothing (or its fallback).

Use a slot in three stepsCopy Anchor Link

import { hookRegistry, type HookContext } from '@salla.sa/twilight-theme-engine/hooks';

hookRegistry.register('header:start', ({ twilight }: HookContext) => (
  <div className="announcement">Free shipping on orders over 200 {twilight.currency?.code}</div>
));

Slot catalogCopy Anchor Link

Names use area:part or area:part.position. Most areas come in .start and .end pairs. Each page below says where the slot sits, what context it passes, and shows an example.

Resolving conflicts and edge casesCopy Anchor Link

Order: priority, then registrationCopy Anchor Link

register(name, handler, priority = 50). Handlers for one name are sorted by priority, higher first. Handlers with the same priority keep the order they were registered in. Every handler renders, one after another, so several handlers on one slot stack up.

hookRegistry.register('footer:end', () => <Second />, 10);
hookRegistry.register('footer:end', () => <First />, 90); // renders first

The engine registers its own defaults with priorities 80 to 100 on body:start (tracking, store-closed notice), body:end, cart:items.start and cart:submit.start. Use a priority below 80 to render after them.

fallback is shown only when the slot is emptyCopy Anchor Link

A slot can have a fallback, which a component passes to HookSlot for content to show when nothing is registered. The moment you register any handler for that name, the fallback is replaced, not added to. To keep the default content, render it yourself in your handler.

useHook removes only its own handlerCopy Anchor Link

useHook registers on mount and, on unmount, removes the handler it registered. Other handlers for the same name stay, including the engine's defaults.

hookRegistry.register works the same way: it returns a function that removes the one handler it added.

const remove = hookRegistry.register('header:start', () => <Promo />);
remove(); // removes only this handler

hookRegistry.clear(name) is different: it removes every handler for the name. Avoid calling it on a slot the engine fills.

The safe pattern is to register once at startup and never clear:

import { defineHooks } from '@salla.sa/twilight-theme-engine/hooks';

defineHooks({
  'header:start': () => <Announcement />,
  'footer:end': [
    { handler: () => <Newsletter />, priority: 60 },
    { handler: () => <Badges />, priority: 40 },
  ],
});

Content from useHook shows only while its component is mounted, and only in the browser: it is never in the server HTML. Use it for content that belongs to one component, and register at startup for content every page should have.

A handler that throws renders nothingCopy Anchor Link

If a handler throws, that handler renders nothing and the other handlers still render. The error is logged only in development. Return null (or nothing) to render nothing on purpose.

ContextCopy Anchor Link

A handler receives the context the slot passes, plus twilight: the full Twilight context (store, theme, currency and more). If your handler needs data the slot does not pass, read it with the matching hook inside the component you return, such as useStore. Type the argument with HookContext:

import type { HookContext } from '@salla.sa/twilight-theme-engine/hooks';

hookRegistry.register('header:start', ({ twilight }: HookContext) => (
  <span>{twilight.store.name}</span>
));

Apps installed on the storeCopy Anchor Link

Besides your handlers, every slot renders a <salla-hook name="..."> element where apps installed on the store inject their content.

• It renders on the client only, to avoid a hydration mismatch when an app changes the DOM before React hydrates.
• The engine's head:* slots pass ssr, so their element is also in the server HTML. Set the ssr prop on your own slot only if no app script will change it.
• Add this rule to your global CSS so the element takes no space:

salla-hook { all: unset; display: none; }

Your own slot name for appsCopy Anchor Link

You can render <HookSlot name="sidebar:top" /> anywhere in your theme. To let installed apps mount into a name of yours, declare it with registerThemeHookSlots. The Salla SDK only lets apps mount into names on its allow list, and this call adds your names to it.

import { registerThemeHookSlots } from '@salla.sa/twilight-theme-engine/utils';

registerThemeHookSlots('sidebar:top', 'sidebar:bottom');

Call it at module scope, so it runs before the page loads. Your own handlers in the registry do not need it.

You replaced a layout or a pageCopy Anchor Link

The slots live inside the engine's Header, Footer, pages and TwilightProvider. If you swap one for your own component, its slots go with it. Render <HookSlot /> with the same names in your version so handlers and apps keep working. The page-frame slots body:start and body:end are rendered by the provider, so they survive a layout swap.

NextCopy Anchor Link

• Page frame slots is the best page to start with.
• HookSlot and useHook document the API.
• Add content to a slot walks through one end to end.