Built-in home blocks

The home page blocks every store has, the data each one receives, and how to replace or reuse them.

Read this when you want to know what a home page block draws, change how one looks, or use one inside your own section.

Salla ships a set of ready-made home page blocks: banners, sliders, product rows and more. Your theme turns each one on in twilight.json, and the merchant can then add it in the theme editor. The engine draws each one with a default component, so you write no code for them. Blocks you declare yourself are covered in Add a home block.

Turn them on

List the blocks your theme supports in the features of twilight.json, as component- plus the name (see twilight.json):

twilight.json
{
  "features": [
    "component-fixed-banner",
    "component-photos-slider",
    "component-square-photos",
    "component-parallax-background",
    "component-youtube",
    "component-store-features",
    "component-testimonials",
    "component-fixed-products",
    "component-products-slider",
    "component-featured-products"
  ]
}

A block that is not listed does not appear in the theme editor.

The blocks

The key is the block's path without home.. Each component receives the block's values as a data prop.

KeyComponentDrawsMain data fields
fixed-bannerFixedBannerOne full-width banner image, with an optional linkimage: { url, alt?, small_url? }, url?, title?
photos-sliderPhotosSliderA slider of imagesitems: [{ image, url?, link_type? }]
square-photosSquarePhotosA grid of square images, the first one biggertitle?, items: [{ image, url?, text? }]
parallax-backgroundParallaxBackgroundA background image that scrolls slower than the page, with an optional title and buttonimage, url?, title?, link_text?, is_opacity?
youtubeYoutubeA YouTube video, loaded when the customer plays ityoutube_id
store-featuresStoreFeaturesA grid of store features, such as free deliveryfeatures: [{ icon, title, description? }]
testimonialTestimonialsCustomer reviews, through the salla-reviews web componenttype? ('store', 'products', 'all'), sort?, limit?, hide_customer_info?, display_all_url?
fixed-productsFixedProductsA grid of productsproducts: { source, source_value? }, title?, limit?, display_all_url?
products-sliderProductsSliderA slider of productsproducts: { source, source_value? }, title?, display_all_url?, autoplay?
featured-products:style1FeaturedProductsStyle1Product groups in tabs, with one main product shown biggeritems: [{ title, products }], main_product?
featured-products:style2FeaturedProductsStyle2Product groups in tabs, each a grid or a slideritems: [{ title, products }], is_slider?
featured-products:style3FeaturedProductsStyle3One featured product next to a column of smaller onesitems: [{ title, featured_product?, products }]
bundle-componentBundleComponentA block from a component bundle the merchant installed, through salla-custom-componentcomponent_name, bundle_id, plus the bundle's own settings

products.source is one of the product list sources, such as 'latest', 'offers' or 'categories' with ids in source_value. See product.list.

The merchant picks one of three styles for featured products. The engine adds the style to the key, so each style has its own component.

Replace a block

Register your component under the same key, after the defaults:

app/router.tsx
import { registerHomeComponents, DefaultHomeComponents } from '@salla.sa/twilight-theme-engine/routes/home';
import { MyBanner } from './components/home/MyBanner';

registerHomeComponents({
  ...DefaultHomeComponents,
  'fixed-banner': MyBanner,
});

Your component gets the same data the table lists. Keep ...DefaultHomeComponents, or every other built-in block disappears. To replace featured products, register the :style1, :style2 and :style3 keys you want to change.

Reuse a block

Each component is exported, so you can draw one inside your own section with your own data:

app/components/home/SaleRow.tsx
import { ProductsSlider } from '@salla.sa/twilight-theme-engine/components/home';

export function SaleRow() {
  return (
    <ProductsSlider
      data={{ products: { source: 'offers' }, title: 'On sale', display_all_url: '/products?source=offers' }}
    />
  );
}

The components load lazily, so the code for a block downloads only when a page uses it.

Gotchas

  • The reviews block's key is testimonial, without an s. The Twig file was called testimonials.
  • A block the merchant added that has no registered component shows a yellow "Unknown component" box in development and nothing in production.
  • bundle-component draws only in the browser, and shows what the bundle's developer built, not your theme. The rest of its data is passed to the bundle as its settings.
  • The first three blocks render with the page. Later blocks mount when they scroll into view.

See also

On this page