# Icon naming conventions that survive a redesign

> Name an icon for what it draws, not for where you first used it. Here is the rule, the three name types to avoid, and how to keep names stable as a product changes.

URL: https://semanticicons.com/blog/icon-naming-conventions
Published: 2026-09-09
Updated: 2026-09-09

An icon named `settings-gear` is fine until the settings page uses a slider instead. An icon named `gear` is still correct, because a gear is still a gear.

That is the whole rule: **name the drawing, not the job.** Everything below follows from it.

## Three name types that go stale

### The place name

`sidebar-toggle`, `header-search`, `checkout-lock`. These bind an icon to a location. Locations move. Within a year you have a `header-search` used in the footer, and nobody trusts the names any more.

### The intent name

`delete`, `confirm`, `danger`. These bind an icon to a meaning. Meanings are reassigned faster than locations. The trash can that means *delete* today means *discard draft* tomorrow, and the red triangle that means *danger* becomes *needs review*.

Intent names also collide. Two designers will both reach for `warning`, and one of them will get `warning-2`.

### The number name

`arrow-1`, `arrow-2`, `arrow-3`. This is what happens when the first two fail. Nobody can pick from this list without opening every file.

## What to use instead

Name the object, in the singular, in lower case, joined by hyphens.

| Instead of | Use |
| --- | --- |
| `delete-button` | `trash-can` |
| `settings-gear` | `gear` |
| `danger-alert` | `triangle-warning` |
| `nav-home` | `house` |
| `success-check` | `check-mark` |

Then put every other word in the keywords, where it belongs. `trash-can` can carry `delete`, `remove`, `bin`, `discard`, `throw it away`, `get rid of it`. The name stays stable and the search still finds it by intent.

This separation is the point. A name is an identifier. A keyword list is an index. Trying to make one string do both jobs is what produces `danger-alert-triangle-warning-icon`.

## Rules that keep a set consistent

- **Singular, always.** `book`, not `books`. Plurals split the set in two, and nobody remembers which one you chose.
- **No type suffix.** Every file in the directory is an icon. `home-icon.svg` says nothing that the directory did not.
- **Order from general to specific.** `arrow-up`, `arrow-up-right`, `arrow-circle-up`. The set then sorts into families on its own.
- **No abbreviations.** `notification`, not `notif`. You will not remember which words you shortened.
- **One word per meaning.** Pick `trash-can` or `bin`, and use it everywhere. A set that uses both has two names for one idea and will grow a duplicate drawing.

That last one is worth enforcing in the build. A uniqueness check on the normalised name and phrase costs nothing and catches the duplicate on the day somebody adds it.

## Handle variants with a suffix, not a new name

A filled version of an outline icon is the same object. Suffix it:

```
bell
bell-filled
bell-slash
bell-slash-filled
```

Not `notification-active`, `notification-muted`. The suffix pattern sorts together, reads clearly, and does not need a decision each time.

## What about a name nobody would search for?

Some objects have an obvious drawing and an unobvious name. A `dustpan` is one. Nobody types `dustpan`.

Keep the accurate name and let the keywords carry the search: `sweep up`, `clean the floor`, `mess`, `crumbs`. This is the case that proves the separation is right. If the name had to be searchable you would call it `cleaning`, and then you would have nowhere to put the broom.

Our set of [3000 icons](/) follows exactly this rule, with about seventeen keywords for each name.

## Questions people ask

### Should icon names match the component names?

No. A component is a job, an icon is a drawing. `DeleteButton` can render `trash-can`. Keeping them separate means you can change what the button shows without renaming a file.

### Is kebab case or camel case better for icon files?

Use kebab case for the files, because file systems differ on case and a lower case name is safe everywhere. Convert to the case your framework wants at build time.

### How do I rename icons without breaking every project?

Keep the old name as an alias that resolves to the new one, and record when you will drop it. A rename with no alias is a breaking change, whatever the version number says.

### Should the category be part of the name?

No. Put it in the metadata. A category in the name means an icon cannot be recategorised without a rename, and some icons genuinely belong in two places.