Socket
Socket
Sign inDemoInstall

astro-icon

Package Overview
Dependencies
Maintainers
1
Versions
30
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

astro-icon - npm Package Compare versions

Comparing version 0.8.1 to 1.0.0-next.0

components/cache.ts
components/Icon.astro
components/index.ts
LICENSE
typings/global.d.ts
typings/iconify.d.ts
typings/integration.d.ts
typings/virtual.d.ts

35

package.json
{
"name": "astro-icon",
"version": "0.8.1",
"version": "1.0.0-next.0",
"type": "module",
"types": "./dist/index.d.ts",
"exports": {
".": "./index.ts",
"./pack": "./lib/createIconPack.ts"
".": {
"types": "./dist/index.d.ts",
"default": "./dist/index.js"
},
"./components": "./components/index.js"
},
"files": [
"lib",
"index.ts"
"components",
"dist",
"typings"
],

@@ -20,2 +25,3 @@ "author": {

"astro",
"astro-integration",
"astro-component",

@@ -40,6 +46,17 @@ "image",

"dependencies": {
"node-fetch": "^3.1.0",
"resolve-pkg": "^2.0.0",
"svgo": "^2.8.0"
"@iconify/tools": "^3.0.1",
"@iconify/types": "^2.0.0",
"@iconify/utils": "^2.1.5"
},
"devDependencies": {
"@astrojs/ts-plugin": "^1.0.6",
"@types/node": "^16.11.7",
"astro": "^2.5.0",
"typescript": "^5.0.4",
"vite": "^4.3.8"
},
"scripts": {
"build": "tsc",
"start": "tsc --watch"
}
}
}

286

README.md

@@ -1,61 +0,68 @@

# Astro Icon
# astro-icon
A straight-forward `Icon` component for [Astro](https://astro.build).
This **[Astro integration](https://docs.astro.build/en/guides/integrations-guide/)** provides a straight-forward `Icon` component for [Astro](https://astro.build).
## Install `astro-icon`.
- <strong>[Why Astro Icon](#why-astro-icon)</strong>
- <strong>[Installation](#installation)</strong>
- <strong>[Usage](#usage)</strong>
- <strong>[Configuration](#configuration)</strong>
- <strong>[Examples](#examples)</strong>
- <strong>[Migrating to v1](#migrating-to-v1)</strong>
- <strong>[Contributing](#contributing)</strong>
- <strong>[Changelog](#changelog)</strong>
```bash
npm i astro-icon
# or
yarn add astro-icon
```
## Why Astro Icon
## Icon Packs
## Installation
`astro-icon` automatically includes all of the most common icon packs, powered by [Iconify](https://iconify.design/)!
### Quick Install
To browse supported icons, check the official [Icon Sets reference](https://icon-sets.iconify.design/) or visit [Icônes](https://icones.js.org/).
Possibly coming soon!
### Usage
<!--
**Icon** will inline the SVG directly in your HTML.
The `astro add` command-line tool automates the installation for you. Run one of the following commands in a new terminal window. (If you aren't sure which package manager you're using, run the first command.) Then, follow the prompts, and type "y" in the terminal (meaning "yes") for each one.
```astro
---
import { Icon } from 'astro-icon'
---
```sh
# Using NPM
npx astro add icon
# Using Yarn
yarn astro add icon
# Using PNPM
pnpm astro add icon
```
<!-- Automatically fetches and inlines Material Design Icon's "account" SVG -->
<Icon pack="mdi" name="account" />
If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.
<!-- Equivalent shorthand -->
<Icon name="mdi:account" />
-->
### Manual Install
First, install the `astro-icon` package using your package manager. If you're using npm or aren't sure, run this in the terminal:
```sh
npm install astro-icon
```
**Sprite** will reference the SVG from a spritesheet via [`<use>`](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/use).
Then, apply this integration to your `astro.config.*` file using the `integrations` property:
```astro
---
import { Sprite } from 'astro-icon'
---
**`astro.config.mjs`**
<!-- 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" />
```js ins={2} "icon()"
import { defineConfig } from "astro/config";
import icon from "astro-icon";
<!-- Equivalent shorthand -->
<Sprite name="mdi:account" />
</Sprite.Provider>
export default defineConfig({
// ...
integrations: [icon()],
});
```
You may also create [Local Icon Packs](#local-icon-packs).
## Usage
## Local Icons
Astro Icon should be ready to go with zero config. The `Icon` component is provided and allows you to inline `svg`s directly into your HTML.
By default, `astro-icon` supports custom local `svg` icons. They are optimized with [`svgo`](https://github.com/svg/svgo) automatically with no extra build step. See ["A Pretty Good SVG Icon System"](https://css-tricks.com/pretty-good-svg-icon-system/#just-include-the-icons-inline) from CSS Tricks.
### Local Icons
### Usage
By default, Astro Icon supports custom local `svg` icons. They are optimized with [`svgo`](https://github.com/svg/svgo) automatically with no extra build step. See ["A Pretty Good SVG Icon System"](https://css-tricks.com/pretty-good-svg-icon-system/#just-include-the-icons-inline) from CSS Tricks.

@@ -66,7 +73,5 @@ 1. Create a directory inside of `src/` named `icons/`.

**Icon** will inline the SVG directly in your HTML.
```astro
---
import { Icon } from 'astro-icon';
import { Icon } from 'astro-icon/components';
---

@@ -78,67 +83,71 @@

**Sprite** will reference the SVG from a spritesheet via [`<use>`](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/use).
## Iconify Icons
```astro
---
import { Sprite } from 'astro-icon';
---
Astro Icon also supports Iconify out-of-the-box with minimal configuration. To use an icon set from Iconify follow the instructions below:
<!-- 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>
```
1. Find an Icon Set to use on the [Iconify Icon Sets website](https://icon-sets.iconify.design/)
2. Install the package (eg. `npm i -D @iconify-json/mdi`)
3. Add an entry to the `astro.config.mjs` file
## Local Icon Packs
**`astro.config.mjs`**
`astro-icon` supports custom local icon packs. These are also referenced with the `pack` and/or `name` props.
```js ins={2}
import { defineConfig } from "astro/config";
import icon from "astro-icon";
1. Create a directory inside of `src/` named `icons/`.
2. Inside that directory, create a JS/TS file with your `pack` name inside of that directory, eg `src/icons/my-pack.ts`
3. Export a `default` function that takes an icon name and returns a svg string. Utilize the `createIconPack` utility to handle most common situations.
export default defineConfig({
// ...
integrations: [
icon({
include: {
mdi: ["*"], // Loads entire Material Design Icon set
},
}),
],
});
```
If using a package from NPM, eg. `heroicons`, the icon pack file would resemble the following:
4. Reference a specific icon using the `name` prop with (eg. `mdi:account`)
```js
import { createIconPack } from "astro-icon/pack";
```astro
---
import { Icon } from 'astro-icon/components'
---
// Resolves `heroicons` dependency and reads SVG files from the `heroicons/outline` directory
export default createIconPack({ package: "heroicons", dir: "outline" });
<!-- Automatically fetches and inlines Material Design Icon's "account" SVG -->
<Icon name="mdi:account" />
```
If using an icon set from a remote server, the icon pack file would resemble the following:
### Props
```js
import { createIconPack } from "astro-icon/pack";
The `Icon` component allows these custom properties:
// Resolves `name` from a remote server, like GitHub! Notice that the `dir` option is not required
export default createIconPack({
url: "https://raw.githubusercontent.com/radix-ui/icons/master/packages/radix-icons/icons/",
});
```ts
interface Props extends HTMLAttributes<"svg"> {
/**
* References a specific Icon
*/
name: string;
title?: string;
size?: number;
width?: number;
height?: number;
}
```
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.
The `Icon` also accepts any global HTML attributes and `aria` attributes. They will be forwarded to the rendered `<svg>` element.
```ts
import { loadMyPackSvg } from "my-pack";
See the [`Props.ts`](./packages/core/lib/Props.ts) file for more details.
export default async (name: string): Promise<string> => {
const svgString = await loadMyPackSvg(name);
return svgString;
};
```
### Styling
## Styling
Styling your `astro-icon` is straightforward. Any styles can be targeted to the `[data-icon]` attribute selector. If you want to target a specific icon, you may target it by name using `[data-icon="filename"]`.
Styling your `astro-icon` 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"]`.
```astro
---
import { Icon } from 'astro-icon';
import { Icon } from 'astro-icon/components';
---
<style lang="css">
[astro-icon] {
[data-icon] {
color: blue;

@@ -148,3 +157,3 @@ /* OR */

}
[astro-icon="annotation"] {
[data-icon="annotation"] {
color: red;

@@ -163,18 +172,107 @@ /* OR */

## Props
### Using with Frameworks
`<Icon>` and `<Sprite>` share the same interface.
Astro Icon can be used with other frameworks utilizing the [`slot` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot). You can read more about how to use Slots in Astro here. [Passing Children to Framework Components](https://docs.astro.build/en/core-concepts/framework-components/#passing-children-to-framework-components)
The `name` prop references a specific icon. It is required.
## Configuration
The `optimize` prop is a boolean. Defaults to `true`. In the future it will control `svgo` options.
### Configuring the Integration
Both components also accepts any global HTML attributes and `aria` attributes. They will be forwarded to the rendered `<svg>` element.
The Astro Icon integration has its own options for controlling the `Icon` component. Change these in the `astro.config.mjs` file which is where your project's integration settings live.
See the [`Props.ts`](./packages/core/lib/Props.ts) file for more details.
#### config.include
## Troubleshooting
If you want to use icon sets from Iconify, specify that set's name using this integration's `config.include` option. To specify including an entire pack use the wildcard `['*']`. Alternatively, loading individual icons is permitted as an array of those icon names.
### Icon not found
**`astro.config.mjs`**
When an icon is not found, `Icon` uses a fallback icon of a black box. This is likely either a typo on the `name` prop or a missing svg file in the `src/icons` folder.
```js ins={2}
import { defineConfig } from "astro/config";
import icon from "astro-icon";
export default defineConfig({
// ...
integrations: [
icon({
include: {
mdi: ["*"], // Loads entire Material Design Icon set
// or
mdi: ["account"], // Only loads the Material Design Icon's "account" SVG
},
}),
],
});
```
#### config.iconDir
If you want to use a different custom svg icon directory instead of the default `src/icons/`, specify that file path using `config.iconDir`
```js ins={2}
import { defineConfig } from "astro/config";
import icon from "astro-icon";
export default defineConfig({
// ...
integrations: [
icon({
iconDir: "src/images/icons",
}),
],
});
```
#### config.svgoOptions
If you want to change the `svgo` options instead of using the defaults, specify the options using `config.svgoOptions`. Read more about the available [`svgo` options here](https://github.com/svg/svgo#configuration)
```js ins={2}
import { defineConfig } from "astro/config";
import icon from "astro-icon";
export default defineConfig({
// ...
integrations: [
icon({
svgoOptions: {
multipass: true,
plugins: [
{
name: "preset-default",
params: {
overrides: {
// customize default plugin options
inlineStyles: {
onlyMatchedOnce: false,
},
// or disable plugins
removeDoctype: false,
},
},
},
],
},
}),
],
});
```
## Examples
TODO: Examples
## Migrating to v1
TODO:
- sprite
- icon packs
## Contributing
You're welcome to submit an issue or PR!
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for a history of changes to this integration.
index.ts
lib/constants.ts
lib/context.ts
lib/createIconPack.ts
lib/Icon.astro
lib/Props.ts
lib/resolver.ts
lib/Sprite.astro
lib/SpriteProvider.astro
lib/Spritesheet.astro
lib/utils.ts
SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc