@gauntlet/state Hooks for app state, products, cart, user, and settings.
@gauntlet/state is how your code reads and changes anything in the app: block config, products, the cart, the signed-in user, navigation, Shopify data. It is a Zustand-backed store, but you reach it only through hooks.
import { useBlock , useBlockSettings , useProductByHandle , useAddToCart } from '@gauntlet/state' Three rules apply to every hook here:
Type the result. Query and metafield hooks return unknown-shaped data; assert your own interface.Null-check before use. Data arrives async — every result can be undefined on first render.Read config through useBlockSettings , never from props — it applies the full settings-precedence chain (Config and theme ).
For the conceptual model behind these hooks, read State and data first.
Hook Parameters When to use useBlockStylethe block from useBlock Resolved style for the block: theme style → theme variant → instance style, deep-merged. useBlockSettingsthe block from useBlock; optional { extends } to inherit a parent block’s settings Read your block’s merged config (global settings → variant → instance). Never read source/options off props directly. useBlockTestIDblock, screenId, optional suffix Stable testID for E2E selectors on a block instance.
Hook Parameters When to use useBuyNowproduct handle; optional checkForRequirements Skip-the-cart purchase action for a product. useCartItemsJust the line items when you don’t need the whole cart. useBackInStockNotificationsgetProduct: (productHandle: string) => any, handle: string, variantId: any, toastSettin… useCheckoutoptional sign-in modal control and continuation Starts checkout, routing through login when the store requires it. useUpdateUserAddressBasedOnLocalization
Hook Parameters When to use useIsStateTruthystr: string useIsStatusIdlestr: string
Hook Parameters When to use useConstants
Hook Parameters When to use useDeepLink
Hook Parameters When to use useEdd
Hook Parameters When to use useSetSortKeyuseQueryDatauseSetQueryDatausePriceDatauseResetFiltersuseFilterStaticData
Hook Parameters When to use useBlockscreenId, componentId, instanceId — all from your BaseBlockProps First call in every block: resolves this placement’s config entry from state. useAppBarscreenId: string useProductTagsproductHandle: string useProductTypeproductHandle: string useCollectionId{ id, handle, } useCheckAndFullfillRequireMentsoptions useAddToCartproduct handle; optional checkForRequirements Returns the add-to-cart action for a product; handles requirement checks (e.g. variant selected). useUpdateQuantityForLineItemuseUpdateQuantityForLineItemsuseUpdateSellingPlanForLineItemuseApplyDiscountCodeApply a discount code to the cart; pair with useRemoveDiscountCode. useRemoveDiscountCodeuseRemoveItemFromCartuseResetCartuseClearGiftItemsuseLineItemsLine items enriched for display (images, options). Prefer useLineItemsV2 in new code. useLineItemsV2useCartThe cart object: items, totals, discounts. Re-renders on cart changes. useModalOpen and close app modals from block code. useAddressuseUserThe signed-in customer (or undefined). Gate account-only UI on it. usePaymentUrluseDomainuseCheckoutInfoscreenId: string useVariantsuseSellingPlanuseVariantsWithSubscriptionuseSelectDefaultVariantPreselect a sensible default variant when a product screen mounts. useSearch{ searchKey, limit } Search results for a query against the store catalog. useDebouncevalue, delay ms Debounced value — search inputs and other rapid-fire state. useAddressFromStorageuseDeviceDimensionsLive screen dimensions for responsive sizing. useDeviceDevice info (platform, notch…) for platform-aware rendering. useThemeTheme tokens (colors, fonts) for styling custom UI consistently. useSettingsRaw settings map for the app. Usually you want useBlockSettings or useGlobalSettings instead. useGlobalStyleApp-wide style defaults blocks inherit. useConfigThe whole app config document. Prefer narrower hooks; reach for this in shell-level code. useProductproductId Product data by id, from store cache or fetched remotely. useProductByHandleproduct handle Product data by handle — the common choice inside product blocks. useProductsByHandlesarray of product handles Batch variant of useProductByHandle for lists and carousels. useCollectionTitleuseCollectionThe active collection and its products on collection screens. useLoadMoreuseFormDataFromStorageuseReRenderKeyGenerates a key that forces a React component to re-render when dependencies change.
Hook Parameters When to use useLocalizationActive country/currency localization state. useCountryCodeuseCurrencyCodeThe active currency code for formatting. useCurrencySymbolcurrencyCode: string usePricea price value Format a price in the shopper’s active currency, conversion included. useConversionRates
Hook Parameters When to use useCollectionMetafieldscollectionId + array of { namespace, key } Collection-level metafields (by-handle variant available). useCollectionMetafieldsByHandlecollectionHandle: string | undefined, listOfNamespaceAndKeys useMultipleMetafieldsproduct handle + array of { namespace, key } descriptors Read product metafields. Assert your own result interface and null-check before access. useMetafieldQueryproduct handle, { namespace, key } list, query options Metafield read with query control (e.g. reference resolution) when useMultipleMetafields is not enough. useShopifyMediaImagesids: Array<MediaImageId> | null, productHandle: string, namespaceAndKeyObj useCollectionMetafieldsQuerycollectionId: string | null | undefined, namespaceAndKeys: Array<Metafield> | Metafield…
Hook Parameters When to use useBottomSheetModalBottom-sheet variant of useModal. useCloseModalOnHardwarebackPress
Hook Parameters When to use useModulemodule name Access optional platform modules (wishlist, reviews…) that may or may not be enabled for the app. useWishlistThe wishlist module when enabled: items plus add/remove actions. useAnalyticsThe analytics module — track custom events from blocks through every configured tracker.
Hook Parameters When to use useOrderDetailsorderId One order’s details for order-history and post-purchase surfaces.
Hook Parameters When to use usePlpGridToggleGrid density on the current product listing: the offered layouts, the active one, and a setter — for building your own density toggle.
Hook Parameters When to use useProductRecommendationshandle: string, mode: 'RELATED' | 'COMPLEMENTARY' useProductDescriptionhandle: string useRecentlyViewedProductshandle: ProductHandle Returns {status, data} useProductByIdsproductIds: Array<ProductId> | null, hideUnavailableProducts
Hook Parameters When to use useQuantityLimitInCartproductTags: Array<string> useMaxVariantInventoryitem: BaseLineItem
Hook Parameters When to use useProductReviewSummaryproductId: string useProductReviewsproductId: string
Hook Parameters When to use useRewardsuseReferralHistoryuseWalletTransactionsuseRedeemedRewardsuseRewardsProgram
Hook Parameters When to use useReplaceScreenReplace the current screen instead of pushing — for redirects. useLinkReturns the navigate action used across the app — screens, products, URLs. The standard way to link. useRouteThe current route and its params. useRouteNameuseSetWebUrluseSetOverrideBack
Hook Parameters When to use useBlockLocationparams: BlockVisibilityParams useActiveScreen
Hook Parameters When to use useSearchKeyuseSetSearchKeyuseGetSearchSuggestionuseIsSearchActiveuseSetIsSearchActiveuseSuggestions{ allowEmpty, limit, } useSuggestionsV2{ allowEmpty, limit, } useGetSearchResultsusePastSearchesuseSetPastSearchesuseTrendingProductslimit: number useSearchRecommendation{ type, limit, idSource, } useTrendingSearches{ limit }: { limit?: number }
Hook Parameters When to use useGlobalSettingsApp-wide settings that are not tied to one block. useIntegrationSettingsthe integration’s configKey Your integration’s merchant-entered settings from integrations.<configKey>. Type the result.
Hook Parameters When to use useShippingAddress
Hook Parameters When to use useShop
Hook Parameters When to use useShopifyQuerya Storefront GraphQL query string Run a typed Storefront query: const data = useShopifyQuery<MyResult>(query). Always null-check.
Hook Parameters When to use useSizeGuide
Hook Parameters When to use useTitlerouteName: string, screenId: string, params: any, options: Record<string, any>
Hook Parameters When to use useVariantSelectoroptions object: productData plus display/selection options The variant-selection engine behind option pickers — selected options, available values, image switching.
Hook Parameters When to use useVideoState{ componentId, instanceId, index, options, }: useVideoStateProps
