# @gauntlet/state (/docs/reference/packages/state) `@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. ```ts import { useBlock, useBlockSettings, useProductByHandle, useAddToCart } from '@gauntlet/state' ``` Three rules apply to every hook here: 1. **Type the result.** Query and metafield hooks return `unknown`-shaped data; assert your own interface. 2. **Null-check before use.** Data arrives async — every result can be `undefined` on first render. 3. **Read config through `useBlockSettings`**, never from props — it applies the full settings-precedence chain ([Config and theme](/docs/concepts/config-and-theme)). For the conceptual model behind these hooks, read [State and data](/docs/concepts/state-and-data) first. ## Hooks by module [#hooks-by-module] {/* generated:begin state-hooks */} ### block [#block] | Hook | Parameters | When to use | | ------------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `useBlockStyle` | the block from useBlock | Resolved style for the block: theme style → theme variant → instance style, deep-merged. | | `useBlockSettings` | the 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. | | `useBlockTestID` | block, screenId, optional suffix | Stable testID for E2E selectors on a block instance. | ### cart [#cart] | Hook | Parameters | When to use | | ----------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | `useBuyNow` | product handle; optional checkForRequirements | Skip-the-cart purchase action for a product. | | `useCartItems` | | Just the line items when you don’t need the whole cart. | | `useBackInStockNotifications` | getProduct: (productHandle: string) => any, handle: string, variantId: any, toastSettin… | | | `useCheckout` | optional sign-in modal control and continuation | Starts checkout, routing through login when the store requires it. | | `useUpdateUserAddressBasedOnLocalization` | | | ### common [#common] | Hook | Parameters | When to use | | ------------------ | ----------- | ----------- | | `useIsStateTruthy` | str: string | | | `useIsStatusIdle` | str: string | | ### constants [#constants] | Hook | Parameters | When to use | | -------------- | ---------- | ----------- | | `useConstants` | | | ### deeplink [#deeplink] | Hook | Parameters | When to use | | ------------- | ---------- | ----------- | | `useDeepLink` | | | ### estimated-delivery-date [#estimated-delivery-date] | Hook | Parameters | When to use | | -------- | ---------- | ----------- | | `useEdd` | | | ### filter [#filter] | Hook | Parameters | When to use | | --------------------- | ---------- | ----------- | | `useSetSortKey` | | | | `useQueryData` | | | | `useSetQueryData` | | | | `usePriceData` | | | | `useResetFilters` | | | | `useFilterStaticData` | | | ### hooks [#hooks] | Hook | Parameters | When to use | | --------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | `useBlock` | screenId, componentId, instanceId — all from your BaseBlockProps | First call in every block: resolves this placement’s config entry from state. | | `useAppBar` | screenId: string | | | `useProductTags` | productHandle: string | | | `useProductType` | productHandle: string | | | `useCollectionId` | \{ id, handle, } | | | `useCheckAndFullfillRequireMents` | options | | | `useAddToCart` | product handle; optional checkForRequirements | Returns the add-to-cart action for a product; handles requirement checks (e.g. variant selected). | | `useUpdateQuantityForLineItem` | | | | `useUpdateQuantityForLineItems` | | | | `useUpdateSellingPlanForLineItem` | | | | `useApplyDiscountCode` | | Apply a discount code to the cart; pair with useRemoveDiscountCode. | | `useRemoveDiscountCode` | | | | `useRemoveItemFromCart` | | | | `useResetCart` | | | | `useClearGiftItems` | | | | `useLineItems` | | Line items enriched for display (images, options). Prefer useLineItemsV2 in new code. | | `useLineItemsV2` | | | | `useCart` | | The cart object: items, totals, discounts. Re-renders on cart changes. | | `useModal` | | Open and close app modals from block code. | | `useAddress` | | | | `useUser` | | The signed-in customer (or undefined). Gate account-only UI on it. | | `usePaymentUrl` | | | | `useDomain` | | | | `useCheckoutInfo` | screenId: string | | | `useVariants` | | | | `useSellingPlan` | | | | `useVariantsWithSubscription` | | | | `useSelectDefaultVariant` | | Preselect a sensible default variant when a product screen mounts. | | `useSearch` | \{ searchKey, limit } | Search results for a query against the store catalog. | | `useDebounce` | value, delay ms | Debounced value — search inputs and other rapid-fire state. | | `useAddressFromStorage` | | | | `useDeviceDimensions` | | Live screen dimensions for responsive sizing. | | `useDevice` | | Device info (platform, notch…) for platform-aware rendering. | | `useTheme` | | Theme tokens (colors, fonts) for styling custom UI consistently. | | `useSettings` | | Raw settings map for the app. Usually you want useBlockSettings or useGlobalSettings instead. | | `useGlobalStyle` | | App-wide style defaults blocks inherit. | | `useConfig` | | The whole app config document. Prefer narrower hooks; reach for this in shell-level code. | | `useProduct` | productId | Product data by id, from store cache or fetched remotely. | | `useProductByHandle` | product handle | Product data by handle — the common choice inside product blocks. | | `useProductsByHandles` | array of product handles | Batch variant of useProductByHandle for lists and carousels. | | `useCollectionTitle` | | | | `useCollection` | | The active collection and its products on collection screens. | | `useLoadMore` | | | | `useFormDataFromStorage` | | | | `useReRenderKey` | | Generates a key that forces a React component to re-render when dependencies change. | ### localization [#localization] | Hook | Parameters | When to use | | -------------------- | -------------------- | --------------------------------------------------------------------- | | `useLocalization` | | Active country/currency localization state. | | `useCountryCode` | | | | `useCurrencyCode` | | The active currency code for formatting. | | `useCurrencySymbol` | currencyCode: string | | | `usePrice` | a price value | Format a price in the shopper’s active currency, conversion included. | | `useConversionRates` | | | ### metafield [#metafield] | Hook | Parameters | When to use | | --------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `useCollectionMetafields` | collectionId + array of \{ namespace, key } | Collection-level metafields (by-handle variant available). | | `useCollectionMetafieldsByHandle` | collectionHandle: string \| undefined, listOfNamespaceAndKeys | | | `useMultipleMetafields` | product handle + array of \{ namespace, key } descriptors | Read product metafields. Assert your own result interface and null-check before access. | | `useMetafieldQuery` | product handle, \{ namespace, key } list, query options | Metafield read with query control (e.g. reference resolution) when useMultipleMetafields is not enough. | | `useShopifyMediaImages` | ids: Array\ \| null, productHandle: string, namespaceAndKeyObj | | | `useCollectionMetafieldsQuery` | collectionId: string \| null \| undefined, namespaceAndKeys: Array\ \| Metafield… | | ### modal [#modal] | Hook | Parameters | When to use | | ---------------------------------- | ---------- | --------------------------------- | | `useBottomSheetModal` | | Bottom-sheet variant of useModal. | | `useCloseModalOnHardwarebackPress` | | | ### module [#module] | Hook | Parameters | When to use | | -------------- | ----------- | ------------------------------------------------------------------------------------------------- | | `useModule` | module name | Access optional platform modules (wishlist, reviews…) that may or may not be enabled for the app. | | `useWishlist` | | The wishlist module when enabled: items plus add/remove actions. | | `useAnalytics` | | The analytics module — track custom events from blocks through every configured tracker. | ### order [#order] | Hook | Parameters | When to use | | ----------------- | ---------- | ----------------------------------------------------------------- | | `useOrderDetails` | orderId | One order’s details for order-history and post-purchase surfaces. | ### plp-grid [#plp-grid] | Hook | Parameters | When to use | | ------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `usePlpGridToggle` | | Grid density on the current product listing: the offered layouts, the active one, and a setter — for building your own density toggle. | ### product [#product] | Hook | Parameters | When to use | | --------------------------- | -------------------------------------------------------------- | ----------------------- | | `useProductRecommendations` | handle: string, mode: 'RELATED' \| 'COMPLEMENTARY' | | | `useProductDescription` | handle: string | | | `useRecentlyViewedProducts` | handle: ProductHandle | Returns \{status, data} | | `useProductByIds` | productIds: Array\ \| null, hideUnavailableProducts | | ### quantity-restriction [#quantity-restriction] | Hook | Parameters | When to use | | ------------------------ | --------------------------- | ----------- | | `useQuantityLimitInCart` | productTags: Array\ | | | `useMaxVariantInventory` | item: BaseLineItem | | ### reviews [#reviews] | Hook | Parameters | When to use | | ------------------------- | ----------------- | ----------- | | `useProductReviewSummary` | productId: string | | | `useProductReviews` | productId: string | | ### rewards [#rewards] | Hook | Parameters | When to use | | ----------------------- | ---------- | ----------- | | `useRewards` | | | | `useReferralHistory` | | | | `useWalletTransactions` | | | | `useRedeemedRewards` | | | | `useRewardsProgram` | | | ### route [#route] | Hook | Parameters | When to use | | -------------------- | ---------- | ---------------------------------------------------------------------------------------------------- | | `useReplaceScreen` | | Replace the current screen instead of pushing — for redirects. | | `useLink` | | Returns the navigate action used across the app — screens, products, URLs. The standard way to link. | | `useRoute` | | The current route and its params. | | `useRouteName` | | | | `useSetWebUrl` | | | | `useSetOverrideBack` | | | ### screen [#screen] | Hook | Parameters | When to use | | ------------------ | ----------------------------- | ----------- | | `useBlockLocation` | params: BlockVisibilityParams | | | `useActiveScreen` | | | ### search [#search] | Hook | Parameters | When to use | | ------------------------- | ------------------------------- | ----------- | | `useSearchKey` | | | | `useSetSearchKey` | | | | `useGetSearchSuggestion` | | | | `useIsSearchActive` | | | | `useSetIsSearchActive` | | | | `useSuggestions` | \{ allowEmpty, limit, } | | | `useSuggestionsV2` | \{ allowEmpty, limit, } | | | `useGetSearchResults` | | | | `usePastSearches` | | | | `useSetPastSearches` | | | | `useTrendingProducts` | limit: number | | | `useSearchRecommendation` | \{ type, limit, idSource, } | | | `useTrendingSearches` | \{ limit }: \{ limit?: number } | | ### settings [#settings] | Hook | Parameters | When to use | | ------------------------ | --------------------------- | --------------------------------------------------------------------------------------------- | | `useGlobalSettings` | | App-wide settings that are not tied to one block. | | `useIntegrationSettings` | the integration’s configKey | Your integration’s merchant-entered settings from integrations.\. Type the result. | ### shipping-address [#shipping-address] | Hook | Parameters | When to use | | -------------------- | ---------- | ----------- | | `useShippingAddress` | | | ### shop [#shop] | Hook | Parameters | When to use | | --------- | ---------- | ----------- | | `useShop` | | | ### shopify-query [#shopify-query] | Hook | Parameters | When to use | | ----------------- | --------------------------------- | ------------------------------------------------------------------------------------------------ | | `useShopifyQuery` | a Storefront GraphQL query string | Run a typed Storefront query: const data = useShopifyQuery\(query). Always null-check. | ### sizing [#sizing] | Hook | Parameters | When to use | | -------------- | ---------- | ----------- | | `useSizeGuide` | | | ### title [#title] | Hook | Parameters | When to use | | ---------- | ------------------------------------------------------------------------------- | ----------- | | `useTitle` | routeName: string, screenId: string, params: any, options: Record\ | | ### variant-selector [#variant-selector] | Hook | Parameters | When to use | | -------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `useVariantSelector` | options object: productData plus display/selection options | The variant-selection engine behind option pickers — selected options, available values, image switching. | ### video [#video] | Hook | Parameters | When to use | | --------------- | ----------------------------------------------------------------- | ----------- | | `useVideoState` | \{ componentId, instanceId, index, options, }: useVideoStateProps | | {/* generated:end */}