Documentation
Feedback
Guides
Storefront Development

Storefront Development
Overriding native components and props
This documentation is currently being developed.
In this guide, you will learn how to modify a component's behavior using additional properties in your store code and create new components by overriding their native equivalents.
These features are useful when you need a customized behavior for a specific component not available in the FastStore native options.
We highly recommend considering overriding props or utilizing the theming tools provided by @faststore/core to achieve the desired behavior. Overriding a component inside a section will compromise the existing integration developed in @faststore/core by losing updates for that component.

Before you start

Ensure you have a functioning FastStore project

Make sure you have a functioning FastStore project after following the FastStore onboarding and setting up the project.

Check the version compatibility of your faststore/core package

This feature is available for stores using @faststore/core 2.1.36 version and above.

Choose a native section and the component you want to customize

The @faststore/core package provides a set of native sections, each consisting of different components with unique functionalities. Refer to the List of native sections and overridable components to explore available native sections.

Consider two aspects for this feature

Keep in mind the following aspects when using this feature:
  • This feature is experimental: The feature may not function as expected.
  • Some sections contain multiple instances of the same component: When overriding a component or passing additional props to it, consider that all instances will be affected by this change.

Override native component's props

Overriding props allows you to customize a component's behavior while preserving its native integration. This approach is useful when you want to modify specific aspects of a native component.
All component customizations in FastStore are performed within a section and to override props, you need to choose the desired native section and component from the List of available native sections.
For this guide, we'll use the BuyButton component to make the customization.
Here's how the initial component looks like with the size prop set as regular in the PDP (Product Details Page):
{"base64":"  ","img":{"width":2858,"height":1582,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":3012700,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/overrides-pdp-buy-button-initial___a4b7ae9d88ed888da5649b2b6cc1eecd.png"}}

Step by step

Step 1 - Setting up the overrides folder

  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 overrides folder. You can run the following command to create them:
macOS and Linux
Windows
  1. Inside the overrides folder, create a new file named after the chosen native section. For example, if you chose the ProductDetails section for customization, create a new file named ProductDetails.tsx under the src/components/overrides directory.
macOS and Linux
Windows
  1. Copy and paste the following code snippet into the file:
copy

_10
import { SectionOverride } from '@faststore/core'
_10
_10
const SECTION = 'ProductDetails' as const
_10
_10
const override: SectionOverride = {
_10
section: SECTION,
_10
components: {}
_10
}
_10
_10
export { override }

Change the value of the SECTION variable to the name of the section you want to override. In the given example, we set the SECTION variable to ProductDetails to override this specific section.
  1. Save your changes.

Step 2 - Setting up the override

  1. Open the ProductDetails.tsx file created in the Setting up the overrides folder step and add the following code:
{8-9}

_12
import { SectionOverride } from '@faststore/core'
_12
_12
const SECTION = 'ProductDetails' as const
_12
_12
const override: SectionOverride = {
_12
section: SECTION,
_12
components: {
_12
BuyButton: { props: { size: 'small', iconPosition: 'right' } },
_12
},
_12
}
_12
_12
export { override }

This code overrides the BuyButton props size and iconPosition. You'll see a smaller button than the initial one, and the cart icon positioned on the right side.
  1. Run yarn dev in the terminal to start the development server. Access the provided localhost URL in your browser and go to product details page to see the updated BuyButton component:
{"base64":"  ","img":{"width":2864,"height":1578,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":3431632,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/overrides-pdp-buy-button-props___898b016bd82c908b5b24c8822be6789a.png"}}
> ⚠️ Remember: props changed via Headless CMS overlap the changes made through override. For example, if you change a prop through override and also change it using Headless CMS, the final prop's value will be the one added using CMS.

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.

Step by step

Step 1 - Create your custom component

  1. Inside the components folder, create a file named CustomBuyButton.tsx. If you haven't created the components folder yet, see the Setting up the overrides folder step.
macOS and Linux
Windows
When creating a custom component, it's important to choose a name that distinguishes it from the native component. For example, Custom{ComponentName} = CustomBuyButton.
  1. Add the following code into CustomBuyButton.tsx file:
copy

_15
import React from 'react'
_15
import { Button as UIButton } from '@faststore/ui'
_15
_15
export function CustomBuyButton() {
_15
return (
_15
<UIButton
_15
variant="primary"
_15
onClick={() => {
_15
alert('Hello User!')
_15
}}
_15
>
_15
New Buy Button
_15
</UIButton>
_15
)
_15
}

The provided code imports the Button component from the @faststore/ui package. The code defines the CustomBuyButton component that displays an alert message when clicked, based on the behavior we want. However, you have the flexibility to customize the component to achieve a different behavior if needed.

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. Navigate to src/components/overrides that we've created before.
  3. Open the ProductDetails.tsx file and update it with the following code:
{8-9}

_13
import { SectionOverride } from '@faststore/core'
_13
import { CustomBuyButton } from '../CustomBuyButton'
_13
_13
const SECTION = 'ProductDetails' as const
_13
_13
const override: SectionOverride = {
_13
section: SECTION,
_13
components: {
_13
BuyButton: { Component: CustomBuyButton },
_13
},
_13
}
_13
_13
export { override }

  1. Run yarn dev in the terminal to start the development server. Access the provided localhost URL in your browser. Navigate to the product details page, you should see the CustomBuyButton component in place of the previous BuyButton component.
{"base64":"  ","img":{"width":1432,"height":788,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":928448,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/overrides-buy-button-open-alert___b62f8cb5f3f98f6bd0f5502081de6a9b.gif"}}
By using your custom component, you may need to customize it from scratch. See Customizing a New Component when using Override guide for more details about styling it.

Overriding components while maintaining default configuration

In specific scenarios, when you want to partially keep the default integration or components configuration, you can use prior integrations within your custom component.
Note that this will only work if your custom component's props are compatible with the overriding component. We encourage using FastStore UI components to leverage existing features, basic styles, and better props compatibility.
Building upon our previous example, we could pass the BuyButton props to our new component. This approach allows us to incorporate the icon and cart sidebar integration while introducing additional functionality to the onClick function, such as triggering an alert or sending an event to analytics.

_17
import React from 'react'
_17
import { Button as UIButton, ButtonProps } from '@faststore/ui'
_17
_17
export function CustomBuyButton(props: ButtonProps) {
_17
return (
_17
<UIButton
_17
{...props}
_17
variant="primary"
_17
onClick={(event) => {
_17
alert('You will love this product!')
_17
props.onClick?.(event)
_17
}}
_17
>
_17
New Buy Button
_17
</UIButton>
_17
)
_17
}

{"base64":"  ","img":{"width":1436,"height":789,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":923029,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/overrides-buy-button-extra___324292e9c8c20cf10f515876a9b33ed1.gif"}}
In this example, when clicked, the CustomBuyButton component will display an alert message and then open the CartSideBar, keeping its default behavior.
This feature can open up numerous possibilities for exploration and customization in your store. Happy exploring! 🎉
Contributors
1
Photo of the contributor
+ 1 contributors
Was this helpful?
Yes
No
Suggest edits (Github)
Contributors
1
Photo of the contributor
+ 1 contributors
On this page