CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-feather-icons

Simply beautiful open source icons with JavaScript API for programmatic access and customization

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

Feather Icons

Feather Icons is a comprehensive icon library providing 287 carefully designed SVG icons on a 24x24 grid with emphasis on simplicity, consistency, and flexibility. The library offers both client-side and server-side JavaScript APIs for programmatically accessing, customizing, and rendering icons with attributes like size, color, and stroke width.

Package Information

  • Package Name: feather-icons
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install feather-icons

Core Imports

const feather = require('feather-icons');

For ES modules:

import feather from 'feather-icons';

Browser (CDN):

<script src="https://unpkg.com/feather-icons"></script>

Basic Usage

const feather = require('feather-icons');

// Access an icon object
const heartIcon = feather.icons.heart;
console.log(heartIcon.name); // 'heart'
console.log(heartIcon.tags); // ['like', 'love', 'emotion']

// Generate SVG markup
const heartSvg = feather.icons.heart.toSvg();
console.log(heartSvg); // '<svg class="feather feather-heart" xmlns="http://www.w3.org/2000/svg"...></svg>'

// Customize SVG attributes
const customHeart = feather.icons.heart.toSvg({
  color: 'red',
  'stroke-width': 1,
  width: 48,
  height: 48
});

// Browser: Replace elements with data-feather attributes
feather.replace(); // Replaces all <i data-feather="heart"></i> with SVG

Architecture

Feather Icons is built around several key components:

  • Icon Objects: Each of the 287 icons is represented as an Icon instance with metadata and rendering methods
  • Icons Collection: A centralized object containing all icon instances, accessible by name
  • SVG Generation: Template-based SVG string generation with customizable attributes
  • DOM Replacement: Browser-only functionality to replace HTML elements with SVG markup
  • Default Attributes: Consistent styling defaults across all icons (24x24, stroke-based design)

Capabilities

Icon Access

Access to the complete collection of 287 icons, each with metadata including name, SVG content, and search tags.

/**
 * Collection of all available icons
 * Each icon is an Icon instance with properties and methods
 */
const icons: {
  [iconName: string]: Icon;
};

/**
 * Icon class representing a single icon with metadata and rendering capabilities
 */
class Icon {
  /** Icon name (kebab-case, e.g., 'arrow-right') */
  name: string;
  
  /** SVG inner content without <svg> wrapper */
  contents: string;
  
  /** Array of search tags for categorization */
  tags: string[];
  
  /** Default SVG attributes applied to all icons */
  attrs: {
    xmlns: string;
    width: number;
    height: number;
    viewBox: string;
    fill: string;
    stroke: string;
    'stroke-width': number;
    'stroke-linecap': string;
    'stroke-linejoin': string;
    class: string;
  };

  /**
   * Generate complete SVG string with customizable attributes
   * @param attrs - Optional attributes to override defaults
   * @returns Complete SVG element as string
   */
  toSvg(attrs?: { [key: string]: string | number }): string;

  /**
   * Return SVG inner content (for backward compatibility)
   * @returns SVG inner markup
   */
  toString(): string;
}

Usage Examples:

// Access icons by name (single-word names can use dot notation)
const homeIcon = feather.icons.home;
const searchIcon = feather.icons.search;

// Multi-word names require bracket notation
const arrowRightIcon = feather.icons['arrow-right'];
const alertCircleIcon = feather.icons['alert-circle'];

// Access icon properties
console.log(homeIcon.name);        // 'home'
console.log(homeIcon.contents);    // '<path d="m3 9 9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/><polyline points="9,22 9,12 15,12 15,22"/>'
console.log(homeIcon.tags);        // ['house', 'building', 'residence']

// Default attributes for consistency
console.log(homeIcon.attrs.width);        // 24
console.log(homeIcon.attrs.height);       // 24
console.log(homeIcon.attrs.viewBox);      // '0 0 24 24'
console.log(homeIcon.attrs.stroke);       // 'currentColor'
console.log(homeIcon.attrs['stroke-width']); // 2

SVG Generation

Generate complete SVG markup with customizable attributes while maintaining design consistency.

/**
 * Generate complete SVG string with customizable attributes
 * @param attrs - Key-value pairs mapped to HTML attributes on <svg> tag
 * @returns Complete SVG element as string
 */
Icon.prototype.toSvg(attrs?: { [key: string]: string | number }): string;

Usage Examples:

// Basic SVG generation
const basicSvg = feather.icons.heart.toSvg();
// Returns: '<svg class="feather feather-heart" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="..."/></svg>'

// Custom size
const largeSvg = feather.icons.heart.toSvg({
  width: 48,
  height: 48
});

// Custom styling
const customSvg = feather.icons.heart.toSvg({
  color: 'red',
  'stroke-width': 1,
  fill: '#ffcccc'
});

// Additional CSS classes (intelligently merged)
const styledSvg = feather.icons.heart.toSvg({
  class: 'my-icon active'
});
// Results in class="feather feather-heart my-icon active"

// Multiple customizations
const fullCustomSvg = feather.icons['arrow-right'].toSvg({
  width: 32,
  height: 32,
  color: '#007bff',
  'stroke-width': 1.5,
  class: 'nav-arrow',
  'data-direction': 'right'
});

DOM Replacement (Browser Only)

Automatically replace HTML elements containing data-feather attributes with corresponding SVG markup.

/**
 * Replace all elements with data-feather attributes with SVG markup
 * Only works in browser environment
 * @param attrs - Optional default attributes applied to all replaced SVGs
 * @throws Error if called in Node.js environment
 */
function replace(attrs?: { [key: string]: string | number }): void;

Usage Examples:

<!-- HTML before replacement -->
<i data-feather="heart"></i>
<i data-feather="star" class="favorite"></i>
<button data-feather="download" disabled>Download</button>

<script>
// Basic replacement
feather.replace();

// With default attributes for all icons
feather.replace({
  'stroke-width': 1,
  width: 20,
  height: 20
});

// Custom attributes are merged with element attributes
feather.replace({
  class: 'icon',
  color: '#666'
});
</script>

<!-- HTML after replacement -->
<svg class="feather feather-heart" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="..."/></svg>
<svg class="feather feather-star favorite" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="..."/></svg>
<svg class="feather feather-download" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" disabled><path d="..."/></svg>

Legacy SVG Generation (Deprecated)

Deprecated function for generating SVG strings. Use Icon.toSvg() instead.

/**
 * Create SVG string for a named icon (DEPRECATED)
 * @deprecated Use feather.icons[name].toSvg() instead
 * @param name - Icon name
 * @param attrs - Optional SVG attributes
 * @returns SVG string
 * @throws Error if icon name is missing or invalid
 */
function toSvg(name: string, attrs?: { [key: string]: string | number }): string;

Usage Examples:

// Deprecated usage (still functional but not recommended)
const heartSvg = feather.toSvg('heart', { color: 'red' });

// Preferred modern usage
const heartSvg = feather.icons.heart.toSvg({ color: 'red' });

// Error handling for invalid names
try {
  const invalidSvg = feather.toSvg('nonexistent-icon');
} catch (error) {
  console.error(error.message); // "No icon matching 'nonexistent-icon'. See the complete list of icons at https://feathericons.com"
}

Available Icons

The library includes 287 icons covering comprehensive categories:

UI & Navigation: arrow-down, arrow-left, arrow-right, arrow-up, chevron-down, chevron-left, chevron-right, chevron-up, home, menu, search, settings, x, plus, minus, check, etc.

Communication & Social: mail, phone, message-circle, message-square, share, heart, star, thumbs-up, thumbs-down, user, users, etc.

Media & Content: play, pause, stop, volume, camera, image, file, folder, edit, trash, download, upload, etc.

Commerce & Business: shopping-cart, credit-card, dollar-sign, trending-up, trending-down, bar-chart, pie-chart, etc.

Technology & Tools: wifi, battery, cpu, hard-drive, smartphone, monitor, printer, etc.

Weather & Time: sun, moon, cloud, clock, calendar, etc.

Alerts & Status: alert-circle, alert-triangle, info, help-circle, check-circle, x-circle, etc.

All icons follow consistent design principles:

  • 24x24 pixel grid
  • 2px stroke width
  • Round line caps and joins
  • Minimalist, outline-based design
  • Scalable vector format

Integration Methods

1. JavaScript API (Programmatic)

const feather = require('feather-icons');
const svg = feather.icons.heart.toSvg({ color: 'red' });

2. Data Attributes (Declarative)

<i data-feather="heart"></i>
<script>feather.replace();</script>

3. SVG Sprite (Static)

<svg><use href="path/to/feather-sprite.svg#heart"/></svg>

4. Individual SVG Files

<img src="path/to/icons/heart.svg" alt="Heart">

Error Handling

The library provides clear error messages for common issues:

  • Invalid icon names: Throws descriptive error with link to complete icon list
  • Server-side DOM operations: Throws environment-specific error for browser-only functions
  • Missing parameters: Validates required parameters and provides helpful messages
  • Graceful warnings: replace() function warns about invalid icons without breaking

Type Definitions

// Main exports
interface FeatherExports {
  icons: IconCollection;
  toSvg: (name: string, attrs?: Attributes) => string; // deprecated
  replace: (attrs?: Attributes) => void;
}

// Icon collection type
interface IconCollection {
  [iconName: string]: Icon;
}

// Attribute type for customization
interface Attributes {
  [key: string]: string | number;
}

// Default attributes structure
interface DefaultAttributes {
  xmlns: "http://www.w3.org/2000/svg";
  width: 24;
  height: 24;
  viewBox: "0 0 24 24";
  fill: "none";
  stroke: "currentColor";
  "stroke-width": 2;
  "stroke-linecap": "round";
  "stroke-linejoin": "round";
  class: string; // "feather feather-{iconName}"
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/feather-icons@4.29.x
Publish Source
CLI
Badge
tessl/npm-feather-icons badge