Skip to content
Twilight React Playground
ثيم رائدaren

usePageConfig

hookAdvancedserverbrowserlive demo

Tells the Salla SDK which page the shopper is on by calling Salla.config.set('page', …) once, when the component mounts.

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

In plain words

Salla's own scripts (the SDK, marketplace apps, analytics) like to know which page the shopper is looking at. Call usePageConfig({ slug: 'product.index', title: 'Chairs' }) in a page component, and the SDK is told once, when the page appears.

It does nothing on the server, and nothing visible: it only updates what Salla.config.get('page') returns.

Signature

function usePageConfig(pageData: PageConfigData): void

interface PageConfigData {
  slug: string;
  id?: string | number;
  title: string;
  url?: string;  // default: the browser address bar's path + query string
  parent?: { id: string | number; name: string; url: string } | null;
}

Try it live

A hidden component calls usePageConfig() once, when it mounts. The buttons read the SDK's page config back, or remount it.Try this: read it, change the title control, read again (unchanged), then press Remount and read once more.
Storefront canvas · ar · RTL
Runs in the browser…
Controls
What a theme writes
import { usePageConfig } from '@salla.sa/twilight-theme-engine/hooks';

export function PageHeading() {
  // Runs once per mount. To report a different page, render the component with a new `key`.
  usePageConfig({ slug: 'product.index', title: 'Chairs' });
  return <h1>{'Chairs'}</h1>;
}

Example

app/components/CategoryHeading.tsx
import { usePageConfig } from '@salla.sa/twilight-theme-engine/hooks';

export function CategoryHeading({ category }: { category: { id: number; name: string } }) {
  usePageConfig({ slug: 'product.index', id: category.id, title: category.name });
  return <h1>{category.name}</h1>;
}

// Remount per category so the SDK hears about each one:
// <CategoryHeading key={category.id} category={category} />

How it behaves

  • Its effect has an empty dependency list: at mount it reads the latest pageData through a ref and calls Salla.config.set('page', { ...pageData, url }).

  • Without Salla.config.set it only warns in development, and never retries.

  • The engine's own pages do not call it.

  • It has no subpath of its own: import it from @salla.sa/twilight-theme-engine/hooks.

Gotchas

  • It runs once per mount. New props (the next category, when the same component stays mounted) do not update the SDK. Give the component a key that changes with the page.

  • The default url is the browser address, not the router location. On localhost and the preview host that address includes the store segment. Pass url yourself when the SDK needs the router path.

  • packages/theme-engine/docs/usePageConfig.md says the URL is detected from the router, that it is SSR compatible, and that it needs TwilightProvider. The code reads window.location, runs only in the browser, and needs no provider.

Related

useBreadcrumbs

Builds a page's breadcrumb trail from its loader data, with a Home-plus-title fallback and a remembered referrer on product pages.

useGtm

Pushes ecommerce events (view, impressions, click, add to cart, checkout, purchase) to Google Tag Manager's dataLayer when the store has GTM.

Source and docs