# Built-in home blocks (https://docs.salla.dev/twilight/react/components/home-blocks)



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](https://docs.salla.dev/twilight/react/recipes/add-a-home-block).

## Turn them on [#turn-them-on]

List the blocks your theme supports in the `features` of `twilight.json`, as `component-` plus the name (see [twilight.json](https://docs.salla.dev/twilight/react/guide/twilight-json)):

```json title="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-blocks]

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

| Key                        | Component                | Draws                                                                                    | Main `data` fields                                                                                       |
| -------------------------- | ------------------------ | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `fixed-banner`             | `FixedBanner`            | One full-width banner image, with an optional link                                       | `image: { url, alt?, small_url? }`, `url?`, `title?`                                                     |
| `photos-slider`            | `PhotosSlider`           | A slider of images                                                                       | `items: [{ image, url?, link_type? }]`                                                                   |
| `square-photos`            | `SquarePhotos`           | A grid of square images, the first one bigger                                            | `title?`, `items: [{ image, url?, text? }]`                                                              |
| `parallax-background`      | `ParallaxBackground`     | A background image that scrolls slower than the page, with an optional title and button  | `image`, `url?`, `title?`, `link_text?`, `is_opacity?`                                                   |
| `youtube`                  | `Youtube`                | A YouTube video, loaded when the customer plays it                                       | `youtube_id`                                                                                             |
| `store-features`           | `StoreFeatures`          | A grid of store features, such as free delivery                                          | `features: [{ icon, title, description? }]`                                                              |
| `testimonial`              | `Testimonials`           | Customer reviews, through the `salla-reviews` web component                              | `type?` (`'store'`, `'products'`, `'all'`), `sort?`, `limit?`, `hide_customer_info?`, `display_all_url?` |
| `fixed-products`           | `FixedProducts`          | A grid of products                                                                       | `products: { source, source_value? }`, `title?`, `limit?`, `display_all_url?`                            |
| `products-slider`          | `ProductsSlider`         | A slider of products                                                                     | `products: { source, source_value? }`, `title?`, `display_all_url?`, `autoplay?`                         |
| `featured-products:style1` | `FeaturedProductsStyle1` | Product groups in tabs, with one main product shown bigger                               | `items: [{ title, products }]`, `main_product?`                                                          |
| `featured-products:style2` | `FeaturedProductsStyle2` | Product groups in tabs, each a grid or a slider                                          | `items: [{ title, products }]`, `is_slider?`                                                             |
| `featured-products:style3` | `FeaturedProductsStyle3` | One featured product next to a column of smaller ones                                    | `items: [{ title, featured_product?, products }]`                                                        |
| `bundle-component`         | `BundleComponent`        | A block from a component bundle the merchant installed, through `salla-custom-component` | `component_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`](https://docs.salla.dev/twilight/react/api/modules/product).

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 [#replace-a-block]

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

```tsx title="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 [#reuse-a-block]

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

```tsx title="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 [#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 [#see-also]

* [Add a home block](https://docs.salla.dev/twilight/react/recipes/add-a-home-block)
* [Home route](https://docs.salla.dev/twilight/react/routes/home)
* [Replace the product card](https://docs.salla.dev/twilight/react/recipes/replace-the-product-card)
