---
title: "File icons"
description: "Show the icon of the file type before the title of a code block, with the icons of the Starlight file tree or a coloured icon set."
url: "https://ewels.github.io/starlight-codeblocks/features/file-icons/"
markdown: "https://ewels.github.io/starlight-codeblocks/features/file-icons.md"
section: "Make code easier to read"
site: "starlight-codeblocks documentation"
context: "This page is from the documentation of starlight-codeblocks. A Starlight plugin that adds focus, line states, annotations, API auto-linking and 22 more features to the code blocks of a site."
index: "https://ewels.github.io/starlight-codeblocks/llms.txt"
---

# File icons

> Show the icon of the file type before the title of a code block, with the icons of the Starlight file tree or a coloured icon set.

A code block with a title shows the file name in the title bar. The plugin puts the icon of the file type before that name. By default, it uses the coloured icons of vscode-icons, the icon theme of VS Code. Two other coloured sets are available. The one-colour Seti set makes a file look the same as in the Starlight `<FileTree>` component.

````md
The default vscode-icons:

```js title="src/index.js"
export const greet = (name) => console.log('Hello', name);
```

Material Icon Theme, with `fileIcons.set="material"`:

```py title="app.py" fileIcons.set="material"
print("Hello from Python")
```

The Seti icons of the Starlight file tree, with `fileIcons.set="seti"`:

```json title="package.json" fileIcons.set="seti"
{ "name": "my-site", "type": "module" }
```

Catppuccin, with `fileIcons.set="catppuccin"`:

```dockerfile title="Dockerfile" fileIcons.set="catppuccin"
FROM node:22-alpine
CMD ["node", "src/index.js"]
```
````

File icons are on for every code block with a title, so you do not add an attribute. The plugin finds the icon from the file name in the title. When the title is not a file name, the icon comes from the language of the code block. The `fileIcons.set` attribute changes the icon set for one block, and the `fileIcons.set` option changes it for the site.

## Syntax

Each attribute goes on the code block fence line. The fence line is the first line of the code block, with the language.

| Syntax | Where |
|---|---|
| `icon="<name>"` | Code block fence line. Sets the icon by name, such as `react`. |
| `icon=false` or `no-icon` | Code block fence line. Removes the icon. |
| `fileIcons.set="vscode-icons"` | Code block fence line. Takes the icon from the coloured vscode-icons icons. |
| `fileIcons.set="material"` | Code block fence line. Takes the icon from the coloured Material Icon Theme icons. |
| `fileIcons.set="seti"` | Code block fence line. Takes the icon from the one-colour Seti icons. |
| `fileIcons.set="catppuccin"` | Code block fence line. Takes the icon from the coloured Catppuccin icons. |
| `fileIcons.style="plain"` | Code block fence line. Shows the icon alone. |
| `fileIcons.style="tile"` | Code block fence line. Shows the icon on a square with rounded corners. |
| `fileIcons.colour="<colour>"` | Code block fence line. Sets a CSS colour for the icon, or for the square of a tile. |

## Examples

### Coloured icons

The `vscode-icons`, `material` and `catppuccin` sets have coloured icons, each with its own rules for file names. [Icon sets](#icon-sets) lists the package that each set needs:

````md
```json title="package.json" fileIcons.set="material"
{ "name": "my-site", "type": "module" }
```

```json title="package.json" fileIcons.set="vscode-icons"
{ "name": "my-site", "type": "module" }
```

```json title="package.json" fileIcons.set="catppuccin"
{ "name": "my-site", "type": "module" }
```

```py title="app.py" fileIcons.set="catppuccin" fileIcons.style="tile"
print("Hello")
```
````

Some icons have a variant for light themes, and the block shows the variant for its theme. In a tile, a coloured icon sits on a neutral square.

### GitHub files

Files in a `.github` folder and `.gitattributes` get the GitHub icon, from the whole path in the title:

````md
```yaml title=".github/workflows/test.yml"
on: [push, pull_request]
```
````

### Icons in a tile

The `tile` style puts a one-colour icon, such as a Seti icon, on a square in the accent colour of the theme. With a custom colour, the icon is black or white, whichever reads on the square:

````md
```py title="app.py" fileIcons.set="seti" fileIcons.style="tile"
print("Hello")
```

```py title="app.py" fileIcons.set="seti" fileIcons.style="tile" fileIcons.colour="#3776ab"
print("Hello")
```

```js title="app.js" fileIcons.set="seti" fileIcons.style="tile" fileIcons.colour="#f7df1e"
console.log('Hello');
```
````

### Set the icon

`icon` sets the icon by name. In the Seti set, the names are the names of the Starlight icons, with or without the `seti:` prefix. Each coloured set has its own names, which [All file icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/all/) shows when you hover over an icon. A Seti name works in every set:

````md
```js title="App" icon="react"
export const App = () => <h1>Hello</h1>;
```
````

### Colour an icon

`fileIcons.colour` takes a CSS colour. Use `light-dark()` to give a different colour in the dark and the light theme:

````md
```toml title="Cargo.toml" fileIcons.colour="light-dark(#f74c00, #b33600)"
[package]
name = "hello"
```
````

### Custom icons

The `fileIcons.icons` option adds icons by name. This site adds the Nextflow icon from Simple Icons, links it to the `.nf` extension and the `nextflow` language, and gives it the Nextflow green:

````md
```nextflow title="main.nf"
workflow {
    Channel.of('Hello').view()
}
```
````

```js title="astro.config.mjs"
import { siNextflow } from 'simple-icons';

codeblocks({
  fileIcons: {
    icons: { nextflow: siNextflow.svg },
    files: { '.nf': 'nextflow', 'nextflow.config': 'nextflow' },
    languages: { nextflow: { icon: 'nextflow', colour: '#31C9AC' } },
  },
});
```

## Behaviour

- How the plugin finds the icon:
  - First, the `icon` attribute.
  - Then the rules of the `fileIcons.files` option, on the whole path in the title.
  - Then the GitHub rules: `.github/**` and `.gitattributes`.
  - Then the rules of the icon set. The Seti set reads the file name at the end of the title, as `<FileTree>` does.
  - In the Seti set, the full name comes first, such as `Dockerfile`. Then the extension, such as `.test.ts` and then `.ts`.
  - Then the language of the code block, such as `py` or `python`.
  - Then the default file icon.
  - A `false` in `fileIcons.files` or `fileIcons.languages` stops the search, and the block gets no icon. The `icon` attribute still sets one.
  - When two keys of `fileIcons.files` match a title, the later key wins.
- Where icons show:
  - In the title of an editor frame. Terminal frames and code blocks with no title get no icon.
  - [Code tabs](https://ewels.github.io/starlight-codeblocks/features/code-tabs/) show the icon of each file on its tab. The code tabs menu shows the icon of each language, custom icons too.
- Colours:
  - A `plain` icon has the colour of the title text.
  - A `tile` has the accent colour of the theme, with the icon in the text colour for that accent.
  - A colour from the site or the code block replaces both.
  - A coloured icon keeps its colours. A colour from the site or the code block draws it in that one colour.
- Screen readers:
  - The icon is decorative. Screen readers read the title only.

With the Seti set, a file in a `<FileTree>` has the same icon as a code block with that file name as its title:

- package.json
- app.py
- Cargo.toml
- Dockerfile
- src/
  - index.js

## Icon sets

The `fileIcons.set` option sets the icons for the whole site. vscode-icons and Seti come with the plugin. Material and Catppuccin each need one package, which you add to the site:

| Set | Icons | Package |
|---|---|---|
| `vscode-icons` | [vscode-icons](https://github.com/vscode-icons/vscode-icons). The default. | None |
| `material` | [Material Icon Theme](https://github.com/material-extensions/vscode-material-icon-theme) | `@iconify-json/material-icon-theme` |
| `catppuccin` | [Catppuccin Icons](https://github.com/catppuccin/vscode-icons), in Macchiato colours, and Latte colours in light themes | `@iconify-json/catppuccin` |
| `seti` | The one-colour icons of the Starlight `<FileTree>` | None |

```sh
npm install @iconify-json/catppuccin
```

The plugin has the file name rules of each set, so a site downloads only the icons of the set that it uses. These files show the icon of each set:

| File | Seti | Material | vscode-icons | Catppuccin |
|---|---|---|---|---|
| JavaScript `index.js` | `javascript` | `javascript` | `file-type-js` | `javascript` |
| TypeScript `index.ts` | `typescript` | `typescript` | `file-type-typescript` | `typescript` |
| React `App.tsx` | `react` | `react-ts` | `file-type-reactts` | `typescript-react` |
| Python `main.py` | `python` | `python` | `file-type-python` | `python` |
| Rust `main.rs` | `rust` | `rust` | `file-type-rust` | `rust` |
| Go `main.go` | `go` | `go` | `file-type-go` | `go` |
| Java `Main.java` | `java` | `java` | `file-type-java` | `java` |
| Kotlin `Main.kt` | `kotlin` | `kotlin` | `file-type-kotlin` | `kotlin` |
| C `main.c` | `c` | `c` | `file-type-c` | `c` |
| C++ `main.cpp` | `cpp` | `cpp` | `file-type-cpp` | `cpp` |
| C# `Program.cs` | `c-sharp` | `csharp` | `file-type-csharp` | `csharp` |
| Ruby `app.rb` | `ruby` | `ruby` | `file-type-ruby` | `ruby` |
| PHP `index.php` | `php` | `php` | `file-type-php` | `php` |
| Swift `main.swift` | `swift` | `swift` | `file-type-swift` | `swift` |
| Shell `install.sh` | `shell` | `console` | `file-type-shell` | `bash` |
| PowerShell `install.ps1` | `powershell` | `powershell` | `file-type-powershell` | `powershell` |
| HTML `index.html` | `html` | `html` | `file-type-html` | `html` |
| CSS `styles.css` | `css` | `css` | `file-type-css` | `css` |
| Sass `styles.scss` | `sass` | `sass` | `file-type-scss` | `sass` |
| JSON `data.json` | `json` | `json` | `file-type-json` | `json` |
| YAML `config.yaml` | `yml` | `yaml` | `file-type-yaml` | `yaml` |
| TOML `config.toml` | `config` | `toml` | `file-type-toml` | `toml` |
| Markdown `notes.md` | `markdown` | `markdown` | `file-type-markdown` | `markdown` |
| MDX `page.mdx` | `mdx` | `mdx` | `file-type-mdx` | `markdown-mdx` |
| Astro `Page.astro` | `astro` | `astro` | `file-type-astro` | `astro` |
| Vue `App.vue` | `vue` | `vue` | `file-type-vue` | `vue` |
| Svelte `App.svelte` | `svelte` | `svelte` | `file-type-svelte` | `svelte` |
| SQL `schema.sql` | `db` | `database` | `file-type-sql` | `database` |
| GraphQL `schema.graphql` | `graphql` | `graphql` | `file-type-graphql` | `graphql` |
| Lua `init.lua` | `lua` | `lua` | `file-type-lua` | `lua` |
| package.json | `json` | `nodejs` | `file-type-npm` | `package-json` |
| tsconfig.json | `tsconfig` | `tsconfig` | `file-type-tsconfig` | `typescript-config` |
| Dockerfile | `docker` | `docker` | `file-type-docker` | `docker` |
| README.md | `info` | `readme` | `file-type-markdown` | `readme` |
| .gitignore | `git` | `git` | `file-type-git` | `git` |
| GitHub workflow `.github/workflows/ci.yml` | `github` | `github` | `github` | `github` |

- [All file icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/all/): See the icon of every language and file name in each set.

## Options

### `fileIcons`

Shows the icon of the file type before the title of a code block. Set it to `false` to turn the feature off. `icon` attributes then have no effect.

- Type: `false | object`
- Default: On

### `fileIcons.set`

The icons: the coloured icons of vscode-icons, Material Icon Theme or Catppuccin, or the one-colour Seti icons of the Starlight file tree. Material and Catppuccin need their `@iconify-json` package, such as `@iconify-json/catppuccin`.

- Type: `'seti' | 'material' | 'vscode-icons' | 'catppuccin'`
- Default: `'vscode-icons'`

### `fileIcons.style`

The icon alone, or the icon on a square with rounded corners. A language or a code block can set its own.

- Type: `'plain' | 'tile'`
- Default: `'plain'`

### `fileIcons.languages`

Settings for the blocks of each language: the icon when the title gives none, as an icon name or SVG markup, or `false` for none, a CSS colour for the icon or the tile, and the style.

- Type: `Record<string, { icon?: string | false; colour?: string; style?: 'plain' | 'tile' }>`
- Default: `{}`

### `fileIcons.files`

Icon names, or `false` for no icon, by file name, such as `nextflow.config`, by extension, such as `.nf`, or by path pattern, such as `.github/**`. A `*` matches within one folder, and `**` across folders. They come before the built-in rules.

- Type: `Record<string, string | false>`
- Default: `{}`

### `fileIcons.icons`

Custom icons by name: SVG markup, or the path data of a 24 by 24 icon. A custom name replaces a built-in icon of the same name.

- Type: `Record<string, string>`
- Default: `{}`

To use tiles on the whole site, with the brand colour of Python and an icon for a custom language:

```js title="astro.config.mjs"
import { siNextflow } from 'simple-icons';

codeblocks({
  fileIcons: {
    style: 'tile',
    icons: { nextflow: siNextflow.svg },
    files: { '.nf': 'nextflow', 'nextflow.config': 'nextflow', 'docs/**/*.md': 'info' },
    languages: {
      python: { colour: '#3776ab' },
      nextflow: { icon: 'nextflow', colour: '#31C9AC' },
    },
  },
});
```

A key in `fileIcons.files` with a `/` or a `*` is a path pattern. `*` matches inside one folder, and `**` matches across folders.

For one language, the icon in `fileIcons.languages` can be SVG markup, with no name in `fileIcons.icons`:

```js title="astro.config.mjs"
codeblocks({
  fileIcons: { languages: { nextflow: { icon: siNextflow.svg } } },
});
```

To show no icon for a file type or a language, use `false`. Here, `.mmd` files and `metro` blocks get no icon, but `overview.mmd` gets the Markdown icon. It comes after `.mmd`, so it wins:

```js title="astro.config.mjs"
codeblocks({
  fileIcons: {
    files: { '.mmd': false, 'overview.mmd': 'markdown' },
    languages: { metro: { icon: false } },
  },
});
```

An icon in `fileIcons.icons` is SVG markup, or the path data of a 24 by 24 icon. An icon with no `fill` takes the colour of the icon. An icon with its own colours keeps them.

The size and the default colours are style settings in the `codeblocksFileIcons` group.

- [Style settings](https://ewels.github.io/starlight-codeblocks/reference/style-settings/): See the size and colour settings of file icons.

## Limitations

- Each set has icons only for the file types that it knows. Other files get the default file icon of the set. Add an icon with `fileIcons.icons`.
- A custom icon with its own colours keeps them in the `tile` style.
- `<FileTree>` sees only the file name, so it shows the YAML icon for a file in `.github/workflows`, where a code block shows the GitHub icon.
- The coloured sets have no GitHub icon, so GitHub files get the Seti icon in every set.
- The plugin carries the rules of each coloured set at one version. An icon that a newer version adds has no rule until the plugin updates its rules.

## Related

- [Code tabs](https://ewels.github.io/starlight-codeblocks/features/code-tabs/): show several files as one block, with the icon of each file on its tab.