astro-iconify
v1.2.0
Published
Fork of astro-icon. Lets you easily use the up to date iconify service as a straight forward astro icon component.
Downloads
1,700
Maintainers
Readme
Astro Iconify
Fork of astro-icon. Lets you easily use the up to date iconify service as a straight forward astro icon component.
Install astro-iconify
.
npm i astro-iconify
# or
yarn add astro-iconify
Icon Packs
astro-iconify
automatically includes all of the most common icon packs, powered by Iconify!
To browse supported icons, check the official Icon Sets reference or visit Icônes.
Usage
Icon will inline the SVG directly in your HTML.
---
import { Icon } from 'astro-iconify'
---
<!-- Automatically fetches and inlines Material Design Icon's "account" SVG -->
<Icon pack="mdi" name="account" />
<!-- Equivalent shorthand -->
<Icon name="mdi:account" />
Sprite will reference the SVG from a spritesheet via <use>
.
---
import { Sprite } from 'astro-iconify'
---
<!-- Required ONCE per page as a parent of any <Sprite> components! Creates `<symbol>` for each icon -->
<!-- Can also be included in your Layout component! -->
<Sprite.Provider>
<!-- Automatically fetches and inlines Material Design Icon's "account" SVG -->
<Sprite pack="mdi" name="account" />
<!-- Equivalent shorthand -->
<Sprite name="mdi:account" />
</Sprite.Provider>
You may also create Local Icon Packs.
Local Icons
By default, astro-iconify
supports custom local svg
icons. They are optimized with svgo
automatically with no extra build step. See "A Pretty Good SVG Icon System" from CSS Tricks.
Usage
- Create a directory inside of
src/
namedicons/
. - Add each desired icon as an individual
.svg
file tosrc/icons/
- Reference a specific icon file using the
name
prop.
Icon will inline the SVG directly in your HTML.
---
import { Icon } from 'astro-iconify';
---
<!-- Loads the SVG in `/src/icons/filename.svg` -->
<Icon name="filename" />
Sprite will reference the SVG from a spritesheet via <use>
.
---
import { Sprite } from 'astro-iconify';
---
<!-- Required ONCE per page as a parent of any <Sprite> components! Creates `<symbol>` for each icon -->
<!-- Can also be included in your Layout component! -->
<Sprite.Provider>
<!-- Uses the sprite from `/src/icons/filename.svg` -->
<Sprite name="filename" />
</Sprite.Provider>
Local Icon Packs
astro-iconify
supports custom local icon packs. These are also referenced with the pack
and/or name
props.
- Create a directory inside of
src/
namedicons/
. - Create a JS/TS file with your
pack
name inside of that directory, egsrc/icons/my-pack.ts
- Use the
createIconPack
utility to handle most common situations.
import { createIconPack } from "astro-iconify";
// Resolves `heroicons` dependency and reads SVG files from the `heroicons/outline` directory
export default createIconPack({ package: "heroicons", dir: "outline" });
// Resolves `name` from a remote server, like GitHub!
export default createIconPack({
url: "https://raw.githubusercontent.com/radix-ui/icons/master/packages/radix-icons/icons/",
});
If you have custom constraints, you can always create the resolver yourself. Export a default
function that resolves the name
argument to an SVG string.
import { loadMyPackSvg } from "my-pack";
export default async (name: string): Promise<string> => {
const svgString = await loadMyPackSvg(name);
return svgString;
};
Styling
Styling your astro-iconify
is straightforward. Any styles can be targeted to the [astro-icon]
attribute selector. If you want to target a specific icon, you may target it by name using [astro-icon="filename"]
.
---
import { Icon } from 'astro-icon';
---
<style lang="css">
[astro-icon] {
color: blue;
/* OR */
fill: blue;
}
[astro-icon="annotation"] {
color: red;
/* OR */
fill: red;
}
</style>
<Icon name="adjustment" /> <!-- will be blue -->
<Icon name="annotation" /> <!-- will be red -->
Props
<Icon>
and <Sprite>
share the same interface.
The name
prop references a specific icon. It is required.
The optimize
prop is a boolean. Defaults to true
. In the future it will control svgo
options.
Both components also accepts any global HTML attributes and aria
attributes. They will be forwarded to the rendered <svg>
element.
See the Props.ts
file for more details.