Getting Started

Meteocons ships as two npm packages — animated SVG and Lottie JSON. Pick the format that fits your project, or install both.

Which format should I use?

Recommendation: use SVG for web projects and Lottie when you need playback control or are building a native app.

Installation

SVG icons

bun add @meteocons/svg

npm install @meteocons/svg

yarn add @meteocons/svg

pnpm add @meteocons/svg

Lottie icons

bun add @meteocons/lottie

npm install @meteocons/lottie

yarn add @meteocons/lottie

pnpm add @meteocons/lottie

Both packages

bun add @meteocons/svg @meteocons/lottie

npm install @meteocons/svg @meteocons/lottie

yarn add @meteocons/svg @meteocons/lottie

pnpm add @meteocons/svg @meteocons/lottie

Quick start

SVG — image tag

The simplest way to render an icon. Animations start automatically.

<img
    src="node_modules/@meteocons/svg/fill/clear-day.svg"
    alt="Clear day"
    width="64"
    height="64"
/>

SVG — bundler import

With a bundler like Vite, Webpack, or Turbopack you can import SVGs directly:

import clearDay from '@meteocons/svg/fill/clear-day.svg';

const img = document.createElement('img');
img.src = clearDay;
img.width = 64;
img.height = 64;
img.alt = 'Clear day';
document.body.appendChild(img);

SVG — inline for full control

Fetch and inline the SVG to access individual elements, apply CSS, or control animations:

const response = await fetch('/icons/fill/clear-day.svg');
const svgMarkup = await response.text();

const container = document.getElementById('weather-icon');
container.innerHTML = svgMarkup;

// Now you can style individual elements with CSS
const svg = container.querySelector('svg');
svg.style.width = '128px';
svg.style.height = '128px';

Lottie — web

Install lottie-web alongside the icon package:

bun add @meteocons/lottie lottie-web

npm install @meteocons/lottie lottie-web

yarn add @meteocons/lottie lottie-web

pnpm add @meteocons/lottie lottie-web

import lottie from 'lottie-web';

const animation = lottie.loadAnimation({
    container: document.getElementById('weather-icon'),
    path: '/path/to/@meteocons/lottie/fill/clear-day.json',
    renderer: 'svg',    // or 'canvas' for better performance
    loop: true,
    autoplay: true
});

// Control playback
animation.setSpeed(0.5);    // half speed
animation.pause();
animation.play();
animation.destroy();        // clean up when done

CDN usage

Use icons directly from a CDN without installing anything. Great for prototyping or static HTML pages.

<!-- unpkg -->
<img
    src="https://unpkg.com/@meteocons/svg/fill/clear-day.svg"
    alt="Clear day"
    width="64"
    height="64"
/>

<!-- jsDelivr -->
<img
    src="https://cdn.jsdelivr.net/npm/@meteocons/svg/fill/clear-day.svg"
    alt="Clear day"
    width="64"
    height="64"
/>

Package structure

Both packages follow the same layout with four icon styles:

@meteocons/svg/
├── fill/              Filled, colorful icons with gradients
├── flat/              Flat design — solid colors, no gradients
├── line/              Outline-based, minimal weight
├── monochrome/        Single-color, inherits currentColor
├── manifest.json      Icon metadata and categories
└── index.d.ts         TypeScript type definitions

Every style directory contains one file per icon, named by slug:

fill/clear-day.svg
fill/rain.svg
fill/snow.svg
fill/thunderstorms-day-rain.svg

The @meteocons/lottie package has the same structure, but with .json files instead of .svg.

Styles

Meteocons comes in four distinct styles. Every icon is available in all four.

The monochrome style is special — it uses currentColor, so the icons automatically match your text color. This makes it ideal for dark mode or themed interfaces:

/* Icons follow the text color */
.weather-widget {
    color: #334155;
}

/* Dark mode — icons adapt automatically */
@media (prefers-color-scheme: dark) {
    .weather-widget {
        color: #e2e8f0;
    }
}

TypeScript

Both packages ship with TypeScript declarations. Import types directly:

import type { IconManifest, IconCategory, IconEntry } from '@meteocons/svg';
import manifest from '@meteocons/svg/manifest.json';

// Full type safety
const categories: IconCategory[] = manifest.categories;
const firstIcon: IconEntry = categories[0].icons[0];

console.log(firstIcon.slug);     // "clear-day"
console.log(firstIcon.animated);  // true

Next steps

• Usage patterns — inline SVG, lazy loading, dynamic icons, accessibility
• Framework guides — React, Vue, Svelte, Angular, and more
• API reference — types, manifest, naming conventions