Adding New Icons
Relevant source files
The following files were used as context for generating this wiki page:The Charlotte project utilizes the Iconify ecosystem to manage and display icons. This approach provides access to a vast library of icons from various sets, which can be easily integrated into Svelte components and configuration files. The primary integration is through the @iconify/svelte component and @iconify-json/* packages for icon data.
This document outlines the process for finding, adding, and using new icons within the project. It covers installing new icon sets, using icons in Svelte components, and configuring them in the site's profile section. An alternative method for creating custom SVG icons programmatically for specific plugins is also discussed.
Icon System Architecture
The icon system is built upon two main types of packages from the Iconify ecosystem: a rendering component and data packages.
@iconify/svelte: A Svelte component that dynamically renders SVG icons.@iconify-json/*: A collection of JSON packages, each containing the data for a specific icon set (e.g., Font Awesome, Material Symbols).
The following diagram illustrates the relationship between these components.
This diagram shows that Svelte components and the site configuration use the @iconify/svelte component, which in turn loads icon data from the installed @iconify-json packages defined in package.json.
Sources: package.json, src/config.ts:103-121, src/components/Search.svelte:3
Adding a New Icon Set
To use an icon from a set not already in the project, you must first add the corresponding Iconify JSON package.
Step-by-Step Guide
-
Find an Icon: Browse icones.js.org to find the desired icon.
-
Identify the Icon Set: Note the icon's set name (e.g.,
fa6-brandsfor Font Awesome 6 Brands). -
Install the Package: Use
pnpmto add the new icon set package to the project's dependencies. The package name follows the format@iconify-json/<icon-set-name>.pnpm add @iconify-json/<icon-set-name>For example, to add the "Font Awesome 6 Brands" icon set:
pnpm add @iconify-json/fa6-brandsThis command is mentioned as a comment in the configuration file.
-
Verify Installation: Check
package.jsonto confirm the new package is listed underdependencies.
The following flowchart visualizes the process of adding a new icon set.
Sources: src/config.ts:106-108, package.json:28-32
Currently Installed Icon Sets
The project already includes several icon sets by default. You can use any icon from these sets without installing new packages.
| Package Name | Prefix |
|---|---|
@iconify-json/fa6-brands | fa6-brands |
@iconify-json/fa6-regular | fa6-regular |
@iconify-json/fa6-solid | fa6-solid |
@iconify-json/material-symbols | material-symbols |
Sources: package.json:28-32
Using Icons
Once an icon set is available, you can use its icons in Svelte components or configuration files.
In Svelte Components
The @iconify/svelte package provides an <Icon> component for use in .svelte files.
-
Import the component:
import Icon from "@iconify/svelte"; -
Use the component in your template: The
iconprop takes a string in the format<prefix>:<icon-name>.<!-- Example from Search.svelte --> <Icon icon="material-symbols:search" class="absolute text-[1.25rem] ..."></Icon> <!-- Another example from Search.svelte --> <Icon icon="fa6-solid:chevron-right" class="..."></Icon>
Sources: src/components/Search.svelte:3, 137, 158
In Site Configuration
Icons can be configured in src/config.ts, particularly for the profile links section. The profileConfig object contains a links array where each link can have an associated icon.
The icon property is a string matching the Iconify format (<prefix>:<icon-name>).
// src/types/config.ts
export type ProfileConfig = {
avatar?: string;
name: string;
bio?: string;
links: {
name: string;
url: string;
icon: string; // The icon string
}[];
};
Sources: src/types/config.ts:74-82
Below is an example from the site's configuration file showing how icons are assigned to profile links.
// src/config.ts
export const profileConfig: ProfileConfig = {
avatar: "assets/images/avatar.webp",
name: "ChuwuYo",
bio: "消失了什么，我不知道",
links: [
{
name: "Bilibili",
icon: "fa6-brands:bilibili", // Icon string
url: "https://space.bilibili.com/404418836",
},
{
name: "GitHub",
icon: "fa6-brands:github", // Icon string
url: "https://github.com/ChuwuYo%22%2C
},
{
name: "Email",
icon: "fa6-solid:envelope", // Icon string
url: "mailto:1805948721@qq.com",
},
],
};
Sources: src/config.ts:101-121
Custom Programmatic SVG Icons
For highly specific use cases, such as in plugins, icons can be created programmatically as HAST (Hypertext Abstract Syntax Tree) elements. This method is used by the pluginCodeToolbar to create copy and success icons for code blocks, bypassing the Iconify system.
This approach involves defining a function that returns an Element object representing the SVG structure.
// src/plugins/expressive-code/code-toolbar.ts
/**
* 创建复制图标 SVG
*/
function createCopyIcon(): Element {
return {
type: "element",
tagName: "svg",
properties: {
viewBox: "0 -960 960 960",
xmlns: "http://www.w3.org/2000/svg",
className: ["toolbar-icon", "copy-icon"],
"aria-hidden": "true",
},
children: [
{
type: "element",
tagName: "path",
properties: {
d: "M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z",
},
children: [],
},
],
};
}
This method is considered advanced and should only be used when the standard Iconify workflow is not suitable.