EDU-18390: Overriding native 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/overriding-native-icons.mdx	https://developers.vtex.com/docs/guides/faststore/managing-icons-overriding-native-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-adding-custom-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-adding-custom-icons

👉 Please review this link before merging your Pull Request.

[github-actions]

🔍 Documentation feedback for docs/faststore/docs/styling/managing-icons/overriding-native-icons.mdx

Here's a review of the provided Guide against the specified rules:

1. General Feedback

The guide is well-written, clear, and follows most of the structural and stylistic guidelines. The instructions are actionable and easy to follow. However, there are a few deviations related to the mandatory frontmatter fields and the prescribed body structure, specifically the presence of an unapproved section and an incorrect section title for the concluding part.

2. Actionable Feedback

1. Missing Mandatory Frontmatter Field: The createdAt field is mandatory but is missing from the frontmatter.
   • Correction: Add a createdAt field with a valid ISO 8601 timestamp (e.g., 2025-04-25T10:00:00Z) to the frontmatter.
2. Unapproved Body Section: The section ## How the override works is present between "Before you begin" and "Instructions". The body rules define a specific sequence of sections (goal-oriented paragraph, Before you begin, Instructions, Next steps) and do not include a standalone explanatory section in this position.
   • Correction: Integrate the content of "How the override works" into the initial goal-oriented paragraph to provide context upfront, or remove it if it's not essential for the "how-to" aspect. For this guide, integrating it into the introduction would enhance clarity without breaking the structure.
3. Incorrect Section Title: The guide uses ## See also at the end. The body rules explicitly state that the concluding section should be titled ## Next steps.
   • Correction: Rename the ## See also section to ## Next steps.

3. Suggested Revision

---
title: "Overriding native icons"
excerpt: "Replace existing FastStore icons with custom SVG designs that match your brand identity."
createdAt: "2024-07-30T10:00:00Z"
---

This guide explains how to override an icon that already ships with FastStore by replacing it with your own SVG design — for example, swapping the default outlined heart for a filled one that matches your brand. To achieve this, you will ship your own `icons.svg` from your store's `/public` folder containing a modified `<symbol>` under the **same `id`** that FastStore components reference. During the build, FastStore copies your file on top of the default one, making your version the active icon source.

If you instead need to add an icon that doesn't exist in the default set, see [Adding custom icons](https://developers.vtex.com/docs/guides/faststore/managing-icons-adding-custom-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-1-setting-up-your-environment) guide.
- The replacement icon available as an SVG file.
- The `id` of the icon you want to override. You can find it in the [Iconography reference](https://developers.vtex.com/docs/guides/faststore/styling-icons).

## 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/         ←
```

### 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 `.faststore/public/icons.svg` into your store's `/public` folder.

```
your-store/
├── src/
├── discovery.config.js
├── package.json
└── public/
    └── icons.svg   ←
```

> ⚠️ If you create an empty `icons.svg` instead of copying the base file, your file completely replaces the default one, and FastStore components will stop rendering their icons.

### Step 3 - Locate the icon to override

Open `/public/icons.svg` and find the `<symbol>` whose `id` matches the icon you want to replace. For example, to override the shopping cart icon, look for:

```svg
<symbol id="ShoppingCart" fill="currentColor" viewBox="0 0 256 256">
  <path d="M..." stroke="currentColor" stroke-linecap="round" stroke-linejoin="round"></path>
  <!-- ... more paths ... -->
</symbol>
```

### Step 4 - Replace the symbol contents

Replace the paths inside the `<symbol>` with your custom design. Keep the same `id` (case-sensitive) and, ideally, the same `viewBox` to preserve consistent sizing:

```svg
<symbol id="ShoppingCart" viewBox="0 0 256 256">
  <!-- Your custom cart paths -->
  <path d="M..." stroke="currentColor" stroke-linecap="round" stroke-linejoin="round"></path>
</symbol>
```

> ⚠️ Any difference in the `id`, including capitalization, will break the override and FastStore will keep rendering the default icon.

### Step 5 - Rebuild your project

Run `yarn dev` (or `yarn build`) to see your changes. Every component that uses the icon, for example, `<Icon name="ShoppingCart" />`, now renders your custom design.

## Next steps

- [Iconography reference](https://developers.vtex.com/docs/guides/faststore/styling-icons)
- [Adding custom icons](https://developers.vtex.com/docs/guides/faststore/managing-icons-adding-custom-icons)
- [Icon component reference](https://developers.vtex.com/docs/guides/faststore/atoms-icon)

---

Was this feedback useful?

• Yes
• No

Review made on commit b90ddce

[github-actions]

✏️ Grammar review summary

docs/faststore/docs/styling/managing-icons/overriding-native-icons.mdx

The document is grammatically correct with the exception of a single missing comma in line 75 before a coordinating conjunction connecting two independent clauses.

---

Was this feedback useful?

• Yes
• No

Review made on commit b90ddce

[github-actions]

📝 [Grammar reviewer] _{reported by reviewdog 🐶}
A comma is required before a coordinating conjunction ('and') that joins two independent clauses.

Suggested change

	> ⚠️ Any difference in the `id`, including capitalization, will break the override and FastStore will keep rendering the default icon.
	> ⚠️ Any difference in the `id`, including capitalization, will break the override, and FastStore will keep rendering the default icon.