Managing icons
Learn how FastStore manages SVG icons and the options available to customize them in your store.
Icons improve web pages by illustrating concepts and improving navigation. FastStore manages icons through a single SVG file, which keeps the storefront fast and consistent while still letting you customize the icon set for your brand.
This guide explains how the icon system works and the customization paths available to you.
All FastStore icons are consolidated in a single SVG file (
icons.svg) shipped with FastStore. This approach offers three main benefits:| Benefit | Description |
|---|---|
| Performance | A single file means a single HTTP request for all icons, instead of one request per icon. |
| Consistency | All icons share the same styling behavior and can be themed via CSS. |
| Maintainability | Centralized icon management makes it easier to audit, add, or replace icons across the storefront. |
Each icon is defined as a
<symbol> element with a unique id inside icons.svg. To render an icon in your storefront, use the Icon component from @faststore/ui and reference the symbol by name:
_10import { Icon } from '@faststore/ui'_10 _10function MyComponent() {_10 return <Icon name="ShoppingCart" weight="regular" />_10}
For the full component details (props, weights, sizes, and data attributes), see the Icon component reference.
Default icon set
FastStore ships with a curated set of icons from Phosphor Icons, covering the most common storefront needs:
- UI actions: Arrows, carets, plus/minus, search, filters.
- Payment methods: Visa, Mastercard, PayPal, Pix, Apple Pay, Google Pay, and others.
- Social media: Facebook, Instagram, Twitter, Pinterest.
- Ecommerce: Shopping cart, heart, star, tag, shipping, map pin.
For the complete list of icons available out of the box, see the Iconography reference.
Customizing icons in your store
There are two ways to customize the icon set in your FastStore project, depending on what you need:
| Scenario | Use this guide |
|---|---|
| You need an icon that doesn't exist in the default set (for example, a WhatsApp icon). | Adding custom icons |
| You want to replace an existing icon with your own design (for example, a custom shopping cart icon that matches your brand). | Overriding native icons |
Both approaches rely on the same underlying mechanism: a custom
icons.svg placed in your store's /public folder, which the build process uses to overwrite the default file.If you create anicons.svgfile in your/publicfolder, it completely replaces the default one. Always start from the base file to avoid breaking icons used by FastStore components. The next sections explain the safe workflow in detail.