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

registerHomeComponentConfig

functionAdvancedserverbrowserlive demo

Sets the placeholder, reserved height, class and id HomeComponentRenderer uses around your own home blocks before they load.

import { registerHomeComponentConfig, HomeComponentConfig } from '@salla.sa/twilight-theme-engine/components/home';

In plain words

Before a home block below the fold loads, the page shows a grey placeholder in its place, so the page does not jump when the real block arrives. For the engine's own blocks those placeholders are already set.

For a block your theme adds, this function says how tall that placeholder should be, what it looks like, and which CSS class and id the block's wrapper gets.

Signature

function registerHomeComponentConfig(config: Record<string, HomeComponentConfig>): void

type HomeComponentConfig = {
  height?: string;                                            // '400px'
  className?: string | ((data: HomeComponentData) => string); // 's-block s-block--<path>'
  id?: string | ((data: HomeComponentData) => string);
  placeholder?: ReactNode;                                    // the products-slider skeleton
};

Try it live

A block that takes 1.5 seconds to load. Its registered config decides the placeholder height and the wrapper class and id.Try this: set height to 250px and load the block again, then press Inspect the wrapper while it is still loading, and once more after.
Storefront canvas · ar · RTL
Runs in the browser…
Controls
Any CSS length. The default for an unknown path is 400px.
What a theme writes
import { registerHomeComponentConfig } from '@salla.sa/twilight-theme-engine/components/home';

// app/router.tsx, next to registerHomeComponents(). "notice" is the block's path.
registerHomeComponentConfig({
  notice: {
    height: '120px',
    className: 's-block s-block--notice container',
    id: 'notice-block',
    placeholder: <div className="animate-pulse rounded bg-gray-100" style={{ height: '120px' }} />,
  },
});

Example

app/router.tsx (excerpt)
import { registerHomeComponentConfig } from '@salla.sa/twilight-theme-engine/components/home';
import { BrandsSkeleton } from './components/home/BrandsSkeleton';

registerHomeComponentConfig({
  brands: {
    height: '220px',
    placeholder: <BrandsSkeleton />,
    className: 's-block s-block--brands container',
  },
  'enhanced-slider': {
    height: 'clamp(200px, 40vw, 520px)',
    id: (block) => `enhanced-slider-${block.key}`,
  },
});

How it behaves

  • Keys are block paths without home., the same names you give registerHomeComponents.

  • height is the wrapper's min-height until the block has rendered; after that the block's own height applies. placeholder shows while the block is off screen and while a lazy block downloads.

  • Calling it again merges by path (Object.assign): other paths keep their config, the same path is replaced.

Gotchas

  • A path you configure loses the engine's built-in config for it entirely, with no field merge: { testimonial: { height: '300px' } } also drops the reviews skeleton, and the block falls back to the products-slider one.

  • className and id functions receive the block as the API sent it, before position is added: data.position is the API's own field, usually absent or null.

  • There is no function to remove a registered config; register the path again to change it.

Related

HomeComponentRenderer

Draws one home page block from its API data: finds its registered component, wraps it in an error boundary, and defers it until visible.

registerHomeComponents

Tells the engine which component draws each home page block, by the block path the Salla API sends. Call it once at startup.

Source and docs