Documentation
Feedback
Guides
Storefront Development

Storefront Development
FastStoreCustomizing sections and componentsSection override
Overriding a native component
Now that you know how to override a component's prop, learn how to override a native component to use a custom component.
For example, you may want to replace the current BuyButton component from the ProductDetails section to meet your business needs. Currently, when the BuyButton is clicked, it opens the CartSideBar as its default behavior:
{"base64":"  ","img":{"width":1435,"height":778,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":1562201,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/overrides-buy-button-open-cart___a5853a88238fa31610a93e8a1333bb00.gif"}}
For this guide we will create a custom Buy Button that once you click on it, it displays an alert for the customer.
Using overrides does not significantly impact performance. FastStore's handling of props and design tokens is designed for good performance.

Before you begin

Make sure your @faststore/core package has the 3.0.0 version or above. If you need to update it, refer to this release note.

Step by step

Step 1 - Setting up the component file

  1. After choosing a native section to be customized from the list of available native sections, open your FastStore project in any code editor of your preference.
  2. Go to the src folder, create the components folder, and inside it, create the sections folder. You can run the following command to create them:
    The naming of the sections folder is arbitrary, as overrides can be created in any file, since the import is made in the src/components/index.tsx file.
    macOS and Linux
    Windows
  3. In the sections folder, create a new file for your customized section. For example, create a new file named ProductDetailsWithCustomButton.tsx under the src/components/sections directory.
  4. Open the ProductDetailsWithCustomButton.tsx file and update it with the following code:
    ProductDetailsWithCustomButton.tsx

    _10
    import { ProductDetailsSection, getOverriddenSection } from '@faststore/core'
    _10
    _10
    const ProductDetailsWithCustomButton = getOverriddenSection({
    _10
    Section: ProductDetailsSection,
    _10
    components: {
    _10
    BuyButton: { Component: CustomBuyButton },
    _10
    },
    _10
    })
    _10
    _10
    export default ProductDetailsWithCustomButton;

Step 2 - Overriding the component

  1. Choose a component to override from the list of overridable components of each native section. In this example, we are overriding the BuyButton component in the ProductDetails section.
  2. In the components folder, if you don't have already the index.tsx file, create the file and add the following:
    components/index.tsx

    _10
    import ProductDetailsWithCustomButton from "./sections/ProductDetailsWithCustomButton";
    _10
    _10
    export default { ProductDetailsWithCustomButton };

Step 3 - Adding the component to the Headless CMS

To integrate the section into the Headless CMS, follow the steps below:
  1. Create a folder named cms in the FastStore root directory.
  2. Inside cms, create the faststore folder.
  3. Within the cms/faststore folder, create the sections.json file.
  4. Add the schema of the new section to the sections.json file, named CustomBuyButton, to the sections.json file:
    sections.json

    _123
    [
    _123
    {
    _123
    "name": "ProductDetailsWithCustomButton.tsx",
    _123
    "requiredScopes": ["pdp"],
    _123
    "schema": {
    _123
    "title": "Custom Buy Button",
    _123
    "description": "A new buy button to display an alert message.",
    _123
    "type": "object",
    _123
    "properties": {
    _123
    "productTitle": {
    _123
    "title": "Product Title",
    _123
    "type": "object",
    _123
    "properties": {
    _123
    "discountBadge": {
    _123
    "title": "Discount Badge",
    _123
    "type": "object",
    _123
    "properties": {
    _123
    "showDiscountBadge": {
    _123
    "title": "Show Discount Badge?",
    _123
    "type": "boolean",
    _123
    "default": false
    _123
    },
    _123
    "size": {
    _123
    "title": "Size",
    _123
    "type": "string",
    _123
    "enumNames": ["Big", "Small"],
    _123
    "enum": ["big", "small"]
    _123
    }
    _123
    }
    _123
    },
    _123
    "refNumber": {
    _123
    "title": "Show Reference Number?",
    _123
    "type": "boolean",
    _123
    "default": false
    _123
    }
    _123
    }
    _123
    },
    _123
    "buyButton": {
    _123
    "title": "Buy Button",
    _123
    "type": "object",
    _123
    "properties": {
    _123
    "title": {
    _123
    "title": "Title",
    _123
    "type": "string",
    _123
    "default": "Add to Cart"
    _123
    },
    _123
    "customAlert": {
    _123
    "title": "Custom Alert Message",
    _123
    "type": "string",
    _123
    "default": "Customize your alert message here"
    _123
    }
    _123
    }
    _123
    },
    _123
    "notAvailableButton": {
    _123
    "title": "Not Available Button",
    _123
    "description": "Shown when a SKU is not available",
    _123
    "type": "object",
    _123
    "properties": {
    _123
    "title": {
    _123
    "title": "Title",
    _123
    "type": "string",
    _123
    "default": "Not Available"
    _123
    }
    _123
    }
    _123
    },
    _123
    "shippingSimulator": {
    _123
    "title": "Shipping Simulation",
    _123
    "type": "object",
    _123
    "properties": {
    _123
    "title": {
    _123
    "title": "Title",
    _123
    "type": "string",
    _123
    "default": "Shipping"
    _123
    },
    _123
    "inputLabel": {
    _123
    "title": "Input Label",
    _123
    "type": "string",
    _123
    "default": "Postal Code"
    _123
    },
    _123
    "link": {
    _123
    "title": "Postal Code Discovery",
    _123
    "type": "object",
    _123
    "properties": {
    _123
    "text": {
    _123
    "title": "Link Text",
    _123
    "type": "string",
    _123
    "default": "I don't know my Postal Code"
    _123
    },
    _123
    "to": { "title": "URL", "type": "string" }
    _123
    }
    _123
    },
    _123
    "shippingOptionsTableTitle": {
    _123
    "title": "Shipping Options Table Header",
    _123
    "type": "string"
    _123
    }
    _123
    }
    _123
    },
    _123
    "productDescription": {
    _123
    "title": "Product Description",
    _123
    "type": "object",
    _123
    "properties": {
    _123
    "initiallyExpanded": {
    _123
    "type": "string",
    _123
    "title": "Initially Expanded?",
    _123
    "enumNames": ["First", "All", "None"],
    _123
    "enum": ["first", "all", "none"]
    _123
    },
    _123
    "displayDescription": {
    _123
    "title": "Should display description?",
    _123
    "type": "boolean",
    _123
    "default": true
    _123
    },
    _123
    "title": {
    _123
    "title": "Description section title",
    _123
    "type": "string",
    _123
    "default": "Description"
    _123
    }
    _123
    }
    _123
    }
    _123
    }
    _123
    }
    _123
    }
    _123
    ]

This schema Adds the new Custom Buy Button section to the Headless CMS.
  1. Open a new terminal window and log in to your VTEX account by running vtex login {accountName}.
  2. Run the following command to sync your changes with the Headless CMS:

    _10
    yarn cms-sync

  3. Access the VTEX Admin and proceed to Storefront > Headless CMS.
  4. Click on the page you desire to add the new section.
  5. Click the add button (+) and add the new section and complete values from the sections fields.
  6. Click Save.

Step 4 - Visualizing the component on the page locally

To see your changes locally, set the Headless CMS preview to the development mode. Refer to the How to preview Headless CMS changes in development mode guide for more information.
Once you have set the preview for development mode, you should see your new Buy Button in a Product Details Page (PDP).

Step 5 - Publishing your changes

If your changes are working in the development mode and you want to publish them, follow the steps below:
  1. Go to the Headless CMS in the VTEX Admin.
  2. Click on a PDP page.
  3. Click Publish to make the new button available on the production store.
Contributors
2
Photo of the contributor
Photo of the contributor
+ 2 contributors
Was this helpful?
Yes
No
Suggest edits (Github)
Contributors
2
Photo of the contributor
Photo of the contributor
+ 2 contributors
On this page