From 96720c59547f4ff811d575e47976b12d4854b12b Mon Sep 17 00:00:00 2001 From: mariana-caetano <67270558+mariana-caetano@users.noreply.github.com> Date: Tue, 19 May 2026 22:02:56 -0300 Subject: [PATCH 1/2] add new content --- .../managing-icons/adding-custom-icons.mdx | 106 ++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 docs/faststore/docs/styling/managing-icons/adding-custom-icons.mdx diff --git a/docs/faststore/docs/styling/managing-icons/adding-custom-icons.mdx b/docs/faststore/docs/styling/managing-icons/adding-custom-icons.mdx new file mode 100644 index 0000000000..50cdfcbfcb --- /dev/null +++ b/docs/faststore/docs/styling/managing-icons/adding-custom-icons.mdx @@ -0,0 +1,106 @@ +--- +title: "Adding custom icons" +excerpt: "Add new SVG icons to your FastStore project when the icon you need isn't part of the default FastStore set." +--- + +This guide explains how to add new SVG icons to your FastStore project when the icon you need isn't part of the [default FastStore icon set](https://developers.vtex.com/docs/guides/faststore/styling-icons), such as a WhatsApp icon for customer support. + +If you want to replace an existing FastStore icon with a different design, see [Overriding native icons](https://developers.vtex.com/docs/guides/faststore/managing-icons-overriding-native-icons). + +## Before you begin + +Make sure you have: + +- A FastStore project set up and running locally. If you don't, refer to the [Setting up the development environment](https://developers.vtex.com/docs/guides/faststore/getting-started-environment-setup) guide. +- The custom icon you want to add available as an SVG file. + +## How the customization works + +To add a custom icon, you ship your own `icons.svg` from your store's `/public` folder. During the build, FastStore copies it on top of the default file, so your version becomes the active icon source — make sure it includes both the default symbols and your new ones. + +## Instructions + +### Step 1 - Create the `/public` folder + +If your project doesn't already have a `/public` folder at the root level, create one: + +``` +your-store/ +├── src/ +├── discovery.config.js +├── package.json +└── public/ ← Create this folder +``` + +### Step 2 - Copy the base `icons.svg` file + +To preserve every default icon, copy the existing file as your starting point: + +1. Run `yarn dev` once to generate the `.faststore` folder in your project. +2. Copy the file from `.faststore/public/icons.svg`. +3. Paste it into your store's `/public` folder. + +``` +your-store/ +├── src/ +├── discovery.config.js +├── package.json +└── public/ + └── icons.svg ← Paste the base file here +``` + +> ⚠️ If you create an empty `icons.svg` without copying the base file first, your file completely replaces the default one, and FastStore components will stop rendering their icons. + +### Step 3 - Prepare your custom icon + +Open the SVG file with your icon and adjust the markup so it works as a symbol entry: + +1. Change the outer `` tag to ``. +2. Add a unique `id` attribute. This is the name you'll use to reference the icon in the `Icon` component. +3. Remove hardcoded `fill`, `stroke-width`, `width`, `height`, and `color` attributes so the icon can be styled through CSS. +4. Use `fill="currentColor"` or `stroke="currentColor"` on the paths so the icon inherits the surrounding text color. +5. Keep the `viewBox` attribute to preserve correct scaling. + +### Step 4 - Add the icon to `icons.svg` + +Open your `/public/icons.svg` file and add the prepared `` inside the root `` element, alongside the existing symbols. + +**Example: Adding a WhatsApp icon** + +```svg + + + + + + + + +``` + +### Step 5 - Use the icon in your components + +Import the `Icon` component from `@faststore/ui` and reference your icon by the `id` you defined: + +```tsx +import { Icon } from '@faststore/ui' + +function CustomerSupport() { + return ( + + + Contact us on WhatsApp + + ) +} +``` + +### Step 6 - Rebuild your project + +Run `yarn dev` (or `yarn build`) to see your changes. + +## See also + +- [Iconography reference](https://developers.vtex.com/docs/guides/faststore/styling-icons) +- [Overriding native icons](https://developers.vtex.com/docs/guides/faststore/managing-icons-overriding-native-icons) +- [Icon component reference](https://developers.vtex.com/docs/guides/faststore/atoms-icon) \ No newline at end of file From 7cb5265182adf2a9014dd112e5b9ba626c4ef33a Mon Sep 17 00:00:00 2001 From: mariana-caetano <67270558+mariana-caetano@users.noreply.github.com> Date: Tue, 19 May 2026 22:06:58 -0300 Subject: [PATCH 2/2] fix link --- .../docs/styling/managing-icons/adding-custom-icons.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/faststore/docs/styling/managing-icons/adding-custom-icons.mdx b/docs/faststore/docs/styling/managing-icons/adding-custom-icons.mdx index 50cdfcbfcb..34da3c21d5 100644 --- a/docs/faststore/docs/styling/managing-icons/adding-custom-icons.mdx +++ b/docs/faststore/docs/styling/managing-icons/adding-custom-icons.mdx @@ -11,7 +11,7 @@ If you want to replace an existing FastStore icon with a different design, see [ Make sure you have: -- A FastStore project set up and running locally. If you don't, refer to the [Setting up the development environment](https://developers.vtex.com/docs/guides/faststore/getting-started-environment-setup) guide. +- A FastStore project set up and running locally. If you don't, refer to the [Setting up the development environment](https://developers.vtex.com/docs/guides/faststore/getting-started-1-setting-up-your-environment) guide. - The custom icon you want to add available as an SVG file. ## How the customization works