EDU-18339 FastStore: Adding custom icons

[mariana-caetano]

Summary

Provide a concise description of the change introduced by this PR.
Example: “Updates the Checkout overview to include new webhook behavior.”

---

Type of change

• New content — Adds new documentation.
• Content update — Improves existing documentation (clarity, structure, examples, accuracy).
• Bug fix — Fixes markdown issues.
• Editorial fix — Spelling, grammar, or minor copy edits that don’t change meaning.
• Content removal — Deletes deprecated or obsolete content.

---

Checklist

• The content follows the VTEX Style Guide.
• Markdown renders correctly (headings, lists, tables, callouts).
• Links, images, code blocks, and examples are valid.
• Terminology, product names, and API references are consistent.
• Frontmatter (title, description, tags, slug) is correct
• Files follow the expected folder structure and naming conventions.

---

AI review instructions

This repository supports automated AI reviews for Markdown files in the docs folder, except docs/localization.

To run reviews on this PR, add at least one of the following labels:

• AI style review: evaluates tone and adherence to VTEX style guidelines.
• AI grammar review: identifies grammar and spelling issues.

Once at least one label is added, the review(s) will run automatically.

After the review is completed, the corresponding label will be removed and the label AI reviewed will be added to the PR.

Note

To rerun a review, remove and add the desired label again.

[github-actions]

👁️‍🗨️ Preview changes on Developer Portal

You can use the link below to load the Developer Portal in preview mode with the changes from this branch:

👉 Open preview environment

Below is the list of modified pages and their corresponding preview URLs:

File	Preview URL	Sidebar
docs/faststore/docs/styling/managing-icons/adding-custom-icons.mdx	https://developers.vtex.com/docs/guides/faststore/managing-icons-adding-custom-icons	⚠️ Missing from navigation.json

[github-actions]

[link-check] _{reported by reviewdog 🐶}
🚨 Found a broken link in a Markdown Link (Error 404):
https://developers.vtex.com/docs/guides/faststore/managing-icons-overriding-native-icons

👉 Please review this link before merging your Pull Request.

[github-actions]

[link-check] _{reported by reviewdog 🐶}
🚨 Found a broken link in a Markdown Link (Error 404):
https://developers.vtex.com/docs/guides/faststore/managing-icons-overriding-native-icons

👉 Please review this link before merging your Pull Request.

[github-actions]

[link-check] _{reported by reviewdog 🐶}
🚨 Found a broken link in a HTML Anchor (Error 400):
https://wa.me/<YOUR_PHONE_NUMBER>

👉 Please review this link before merging your Pull Request.

[github-actions]

🔍 Documentation feedback for docs/faststore/docs/styling/managing-icons/adding-custom-icons.mdx

This review evaluates the Adding custom icons guide based on the VTEX Developer Portal rules.

1. General Feedback

The guide is technically sound, clear, and follows the imperative tone required for documentation. However, it deviates from the mandatory structure and metadata requirements. Specifically, it is missing required frontmatter fields (slug, createdAt), includes a conceptual section between "Before you begin" and "Instructions" which breaks the standard flow, and uses "See also" instead of the prescribed "Next steps" heading.

---

2. Actionable Feedback

• Frontmatter:
  • Add the slug field (e.g., adding-custom-icons).
  • Add the createdAt field in ISO 8601 format.
• Structure (R1.1):
  • The section "How the customization works" should be integrated into the introduction or the first step. The standard flow must be: Intro -> Before you begin -> Instructions.
  • Rename the "See also" section to "Next steps" to align with the Guide template.
• Tone and Voice (R2.5):
  • Ensure all numbered list items start with an imperative verb. Most already do, but double-check that no descriptive sentences precede the action in those lists.
• Step Headings:
  • The current step headings are correct (### Step N - Imperative title), but ensure the content within them remains focused on the action.

---

3. Suggested Revision

---
title: Adding custom icons
slug: 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.
createdAt: 2025-03-05T14:00:00Z
---

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). To add a custom icon, you provide your own `icons.svg` file in the `/public` folder. During the build, FastStore uses this file to override the default set, allowing you to include both native and custom symbols.

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.

## Instructions

### Step 1 - Create the /public folder

Create a `/public` folder at the root level of your project if it does not already exist:

```
your-store/
├── src/
├── discovery.config.js
├── package.json
└── public/         ← Create this folder
```

### Step 2 - Copy the base icons.svg file

Copy the existing icon set to your new folder to ensure you preserve all default icons:

1. Run `yarn dev` in your terminal to generate the `.faststore` folder.
2. Copy the `icons.svg` file from `.faststore/public/`.
3. Paste the file into your store's `/public` folder.

> ⚠️ If you use an empty `icons.svg` file, it will completely replace the default set, and native FastStore components will fail to render their icons.

### Step 3 - Prepare your custom icon

Open your custom SVG file and adjust the markup to format it as a symbol:

1. Change the outer `<svg>` tag to `<symbol>`.
2. Add a unique `id` attribute to reference the icon in your code.
3. Remove hardcoded `fill`, `stroke-width`, `width`, and `height` attributes to allow CSS styling.
4. Apply `fill="currentColor"` or `stroke="currentColor"` to the paths so the icon inherits text colors.
5. Keep the `viewBox` attribute to ensure correct scaling.

### Step 4 - Add the icon to icons.svg

Open your `/public/icons.svg` file and paste your prepared `<symbol>` inside the root `<svg>` element.

**Example: Adding a WhatsApp icon**

```svg
<svg style="display:none">
  <!-- ... existing icons ... -->

  <!-- Your custom icon -->
  <symbol id="WhatsApp" viewBox="0 0 256 256">
    <path d="M128,24A104,104,0,0,0,36.18,176.88L24.83,210.93a16,16,0,0,0,20.24,20.24l34.05-11.35A104,104,0,1,0,128,24Zm0,192a87.87,87.87,0,0,1-44.06-11.81,8,8,0,0,0-4-1.08,7.85,7.85,0,0,0-2.53.42L40,216,52.47,178.6a8,8,0,0,0-.66-6.54A88,88,0,1,1,128,216Z" fill="currentColor"/>
  </symbol>
</svg>
```

### Step 5 - Use the icon in your components

Import the `Icon` component from `@faststore/ui` and reference your icon using the `id` you defined:

```tsx
import { Icon } from '@faststore/ui'

function CustomerSupport() {
  return (
    <a href="https://wa.me/<YOUR_PHONE_NUMBER>">
      <Icon name="WhatsApp" />
      <span>Contact us on WhatsApp</span>
    </a>
  )
}
```

### Step 6 - Rebuild your project

Run `yarn dev` or `yarn build` to apply the changes and view your new icon.

## Next steps

- [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)

---

Was this feedback useful?

• Yes
• No

Review made on commit 96720c5