Experimental exports - Hooks and Components

FastStore provides hooks and components to extend native features within your custom sections and overridden components.

For example, you can create a custom BuyButton that adds products to the cart and displays a personalized message based on user preferences or order history.

Before you begin

All experimental hooks and components are suffixed with _unstable, indicating they are available for use but may not function as expected or could have limitations with certain store customizations. Before deploying them in a production environment, make sure to test them to confirm compatibility with your store.

Instructions

Open your store project in a code editor, then open the component or section file where you want to import the hook or component.
Import the hook or component into your custom component file.

_10import { use{ComponentName}_unstable as use{ComponentName} } from '@faststore/core/experimental'

Replace {ComponentName} with the name of the component you want to import, for example useCartToggleButton.
Incorporate the imported hook or component into your custom component logic. In the following example, the useCartToggleButton_unstable hook enables toggling the cart.

_17import React from "react"; _17import { Button as UIButton } from "@faststore/ui"; _17import { useCartToggleButton_unstable as useCartToggleButton } from "@faststore/core/experimental"; _17 _17export default function CustomBuyButton() { _17 const { onClick: toggleCart } = useCartToggleButton(); _17 return ( _17 <UIButton _17 variant="primary" _17 onClick={() => { _17 toggleCart(); _17 }} _17 > _17 New Buy Button _17 </UIButton> _17 ); _17}
Save your changes.
Open a terminal and run yarn dev to test the implementation.

List of hooks and components

Explore the features of the experimental hooks and the Image_unstable component.

Hooks
- useCart_unstable API reference
Image_unstable

Hooks

Hooks provide features or statuses of native components that you can integrate into your custom components. Here's a list of available hooks:

Authentication

Hook	Description
`useAuth_unstable`	Accesses authentication status and actions.

Cart

Hook	Description
`cartStore_unstable`	Stores and retrieves cart details.
`useCart_unstable`	Accesses the current cart's status and actions. For more details on this hook's properties and functions, see useCart_unstable - API reference.
`useBuyButton_unstable`	Leverages the behavior of the native BuyButton.
`useCartToggleButton_unstable`	Adds a cart toggle feature to custom components.
`useCheckoutButton_unstable`	Leverages the behavior of the native checkout button.
`useRemoveButton_unstable`	Leverages the behavior of the native remove button.

Delivery Promise

Hook	Description
`deliveryPromiseStore_unstable`	Stores and retrieves Delivery Promise data (pickup points, default/global selection, simulation state).
`useDeliveryPromise_unstable`	Accesses and manages Delivery Promise state, pickup points, delivery-related facets, labels, and badges.

GraphQL

Hook	Description
`useLazyQuery_unstable`	Retrieves data from a GraphQL endpoint on demand.
`useQuery_unstable`	Retrieves data from a GraphQL endpoint.

Hook	Description
`useNewsletter_unstable`	Accesses the newsletter subscription feature.

Product

Hook	Description
`useDiscountPercent_unstable`	Calculates the discount percentage for a given price.
`useFormattedPrice_unstable`	Formats a price value based on the current locale.
`useLocalizedVariables_unstable`	Provides localized variables for use in components.
`useCreateUseGalleryPage_unstable`	Handles the creation of a gallery page.
`useGalleryPage_unstable`	Manages the state and functionality of a gallery page.
`UseGalleryPageContext_unstable`	Provides access to and management of the context for a gallery page.
`useProductGalleryQuery_unstable`	Retrieves product gallery images.
`useProductLink_unstable`	Generates a product link based on the product ID.
`useProductQuery_unstable`	Retrieves product details.
`useProductsPrefetch_unstable`	Preloads product details for a given list of product IDs.

Search

Hook	Description
`useDelayedFacets_unstable`	Delays facet application to improve performance.
`useDelayedPagination_unstable`	Delays pagination to improve performance.
`useFilter_unstable`	Enables filtering for product listings.
`useSearchHistory_unstable`	Accesses the user's search history.
`useSuggestions_unstable`	Provides suggestions based on the user's search query.
`useTopSearch_unstable`	Retrieves the top search results.

Session

Hook	Description
`sessionStore_unstable`	Stores and retrieves session data.
`useSession_unstable`	Accesses and manages current session information.
`validateSession_unstable`	Validates the current user session.

Shipping

Hook	Description
`getShippingSimulation_unstable`	Retrieves the shipping simulation data, which can be used to display shipping costs, options, and delivery estimates.
`useShippingSimulation_unstable`	Runs and manages shipping simulations to display costs, options, and delivery estimates.

UI

Hook	Description
`useScreenResize_unstable`	Adapts the interface to different screen sizes and devices.

useCart_unstable API reference

The useCart_unstable hook returns an object with the following properties and functions:

Variable name	Type	Description
`addItem`	`(item: T) => void`	Adds an item to the cart.
`emptyCart`	`() => void`	Removes all items from the cart.
`getItem`	`(id: string) => T \| undefined`	Retrieves an item from the cart by its `id`. Returns `undefined` if not found.
`id`	`string`	Gets the cart's unique identifier.
`inCart`	`(id: string) => boolean`	Checks if an item with the given `id` exists in the cart.
`isEmpty`	`boolean`	Returns `true` if the cart is empty.
`isValidating`	`boolean`	Returns `true` if the cart is being validated (e.g., syncing with a server).
`items`	`Item[]`	Gets the current items in the cart.
`removeItem`	`(id: string) => void`	Removes an item from the cart by its `id`.
`setCart`	`(cart: Cart) => void`	Replaces the current cart with a new one.
`updateItemQuantity`	`(id: string, quantity: number) => void`	Updates the quantity of a given item in the cart.

`Image_unstable` component

Use the Image_unstable component to optimize image performance in your storefront. This component uses Thumbor for image resizing, cropping, and caching the results on a Content Delivery Network (CDN). Use it whenever you need to create a new section for the Headless CMS.


_16import { HeroImage as UIHeroImage } from "@faststore/ui";
_16import { Image_unstable as Image } from "@faststore/core/experimental";
_16
_16export default function CustomHeroImage() {
_16  return (
_16    <UIHeroImage>
_16      <Image
_16        src="https://storeframework.vtexassets.com/arquivos/ids/160965/est.jpg?v=637752924295370000"
_16        alt="Two puffs and two small desks placed together, accompanied by various color pencils."
_16        width={360}
_16        height={240}
_16        sizes="(max-width: 360px) 50vw, (max-width: 768px) 90vw, 50vw"
_16      />
_16    </UIHeroImage>
_16  );
_16}