Overriding Native Components and Props

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.

Before you start

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):

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:

mkdir src/components src/components/overrides

3. 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.

touch src/components/overrides/ProductDetails.tsx

4. Copy and paste the following code snippet into the file:

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

5. 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:

import { SectionOverride } from '@faststore/core'
 
const SECTION = 'ProductDetails' as const
 
const override: SectionOverride = {
  section: SECTION,
  components: {
    BuyButton: { props: { size: 'small', iconPosition: 'right' } },
  },
}
 
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.

2. 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:

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:

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.

touch src/components/CustomBuyButton.tsx

2. Add the following code into CustomBuyButton.tsx file:

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

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:

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

4. 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.

By using your custom component, you may need to style 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.

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.

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

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! 🎉