Composables

Overview

Composables pack related actions together so that you can use them within Vue components. The action is then connected by @click handler on a button. The composables are also designed to share state, even when used in different components.

Example

Actions related to the basket that need to be re-used frequently include:

Adding or removing a product to the basket
Getting a count of all products in the basket
Retrieving all products in the basket
Determining if a product is already in the baskets.

Basket composable

const {
  addItem,
  removeItem,
  count,
  items,
  contains
} = useBasket()

To add a product to a basket, connect the addItem method to a @click handler on a button.

The composables are designed to share state, even when used in different components. If you have a header component that shows the current count of products and a product component that has an "Add to Basket" button. Both components call useBasket(), but only a single request is sent to the Storefront API. Additionally, clicking the "Add to Basket" button in the product component will also automatically update the count in the header component because they share the same basket.

Composables

useBasket

Manage the basket of the current user. useBasket composable allows you to:

Add items to the basket

This will add the product variant 123456 with a quantity of 3 into the basket.

const { addItem } = await useBasket()

await addItem({
  variantId: 123456,
  quantity: 3,
})

The default behavior for adding items to the basket is to add the quantity to existing items. So if there was already a quantity of 1 of 123456, you would end up with 4.

If you want to end up with a quantity of 3, you can change this behavior:

await addItem({
  variantId: 123456,
  quantity: 3,
  existingItemHandling: ExistingItemHandling.ReplaceExisting
})

Using ExistingItemHandling.ReplaceExisting is a good idea, if you have buttons in your UI that increase or decrease the quantity of a product.

Remove items from the basket

This will remove the variant 123456 from the basket.

const { removeItem } = await useBasket()

await removeItem({
  variantId: 123456,
})

Clear the basket

This will clear the entire basket.

const { clearBasket } = await useBasket()

await clearBasket()

Check if an item is inside the basket

This will check if a specific item is in the basket.

const { contains } = await useBasket()

console.log("Variant 123456", contains({
  variantId: 123456,
}))

console.log("Product 789", contains({
  productId: 789,
}))

contains allows you to either check if a specific variant is in the basket or if a product (and any of its variants) is in the basket.

Get the number of items inside the basket

This will provide the number of items in the basket.

const { count } = await useBasket()

console.log("Number of items", count.value)

count stores the number of items contained inside the basket. This is commonly used for showing a badge in the navigation bar or a total count on the basket page.

useCategories

Fetch category information based on a given path.

Fetch categories for a given path

This example loads all sub-categories of the “/women” category and lowers children up to three layers. Fetching more layers underneath is useful if you want to create a category tree in the navigation.

const { data: categories } = await useCategories({
    params: { path: "/women", children: 3 },
})

console.log("Active node", data.value.activeNode)
console.log("Children", data.value.categories)

useFacet

useFacet is a complex facet, bringing together a lot of functionality that you would usually have to call individually for a common product listing page. It combines loading products and categories and automatically provides available filters based on the search criteria, quick filters, and product counts. \

See the chapter Faceted Search in the Developer Guide for more information.

Load all products, categories, and filters for a category path

const { fetchProducts, products, categories, selectedCategory } = await useFacet()

await fetchProducts({ path: '/women'})

console.log("Products", products.value)
console.log("Current category", selectedCategory.value)
console.log("Sub Categories", categories.value)

Pagination

useFacet also takes care of pagination logic for us. We can control the number of products per page and manually fetch new pages:

const { fetchProducts, pagination, fetchPage } = await useFacet()

await fetchProducts({ path: '/women', perPage: 25})

await fetchPage(pagination.value.page + 1) // Fetching page 2

Apply filters

Filtering products allows you to only reduce the number of products and keep the current category and all the other information the same.

const { filterProducts } = await useFacet()

// We don't show the product fetching here
// [...]

await filterProducts({
  where,
  sort
})

useFilters

Retrieve all available filters inside a given category. You could use this information to build a filter slide-in.

Load filters for a category

const { data: filters } = useFilters({ params: { category: '/women'} })

Additional properties for fetching are:

includedFilters: string[] list of filters to include in the query
where provide additional conditions for filtering product data

useWishlist

Manage the wishlist of the current user.

Add items to the wishlist

const { addItem } = await useWishlist()

await addItem({
  variantId: 123456,
})
await addItem({
  productId: 123,
})

This will add the variant 123456 as well as the product 123 to the wishlist.

Remove items from the wishlist

This will remove variant 123456 and product 123 from the wishlist.

const { removeItem } = await useWishlist()

await removeItem({
  variantId: 123456,
})
await removeItem({
  productId: 123,
})

Toggle an item on the wishlist

This will add an item, if it is not on the wishlist yet, or remove it.

const { toggleItem } = await useWishlist()

await toggleItem({
  variantId: 123456,
})
await toggleItem({
  productId: 123,
})

This is a very useful helper that can be used on an “Add To Wishlist/Remove from Wishlist Button” on your product cards.

Check if an item is on the wishlist

This is a helper function to check if an item is added to the wishlist.

const { contains } = await useWishlist()

console.log("In wishlist?", contains({
  variantId: 123456,
}))

In combination with toggleItem this can create very powerful components:

<button @click="toggleItem({ variantId: 123456 })">
  <component :is="contains({ variantId: 123456 }) ? 'FilledHeartIcon' : 'EmptyHeartIcon'" />
</button>

Replace an item on the wishlist

This is a helper method that, in this example, removes variant 123456 from the wishlist and then adds 987654.

const { replaceItem } = await useWishlist()

await replaceItem({ variantId: 123456 }, { variantId: 987654})

This is very useful when you have a “Change Size” selector on the wishlist page and want to change the size of a product on the wishlist.

Clear the wishlist

This will clear the wishlist.

const { clearWishlist } = await useWishlist()

await clearWishList()

useUser

Manage user data and fetch the currently logged-in user state.

This is commonly used in the Header component for showing the user name if he is logged in.

const { user, isLoggedIn, fetch } = await useUser()

console.log("User logged in?", isLoggedIn.value, user.value?.firstName)

Changing the user data

updateUser can be used to update the user details:

import type { ShopUser } from '@scayle/storefront-nuxt'
const { updateUser } = useUser()

await updateUser(user: ShopUser)