@telperion/elements

A collection of custom web components built with Lit Elements. This library provides a suite of reusable, framework-independent web components for modern web applications.

✨ Features

• 🌐 Framework Independent: Built as custom web elements, works with any framework (React, Vue, Angular, Vanilla JS)
• 🔧 Custom Components: A growing collection of useful web components
• 🎨 CSS Custom Properties: Rich CSS variable support for styling
• 📦 Modular: Import only the components you need
• 🔄 Reactive: Built on Lit's reactive properties system
• 🎯 TypeScript: Full TypeScript support with type definitions

📦 Installation

npm install @telperion/elements

yarn add @telperion/elements

pnpm add @telperion/elements

Tailwind v4 consumers: some elements (e.g. <tp-icon>) render Tailwind utility classes from inside the published package. Add @source "@telperion/elements"; to your Tailwind entry CSS so the JIT scanner picks them up. See each module's README for details.

🚀 Usage

import '@telperion/elements';

// Use the components in your HTML

Loading via <script> tag (no bundler)

Every component module ships a self-contained, minified IIFE bundle that you can load directly from a CDN with a classic <script> tag — no bundler, no import, no npm install.

Use the explicit /iife/... path so the CDN serves the standalone bundle (subpath shorthand like /icon resolves to the ESM build via the package exports map and will not run as a classic script):

<!-- All elements registered (TelperionElements global) -->
<script src="https://unpkg.com/@telperion/elements/iife/elements.js"></script>

<!-- Or just the icon module (TelperionElements.Icon) -->
<script src="https://unpkg.com/@telperion/elements/iife/icon/index.js"></script>

<!-- Or just the router module (TelperionElements.Router) -->
<script src="https://unpkg.com/@telperion/elements/iife/router/index.js"></script>

<!-- Or just the drag-and-drop module (TelperionElements.DragDrop) -->
<script src="https://unpkg.com/@telperion/elements/iife/drag-drop/index.js"></script>

Each per-module bundle is fully self-contained: side-effect imports register the custom elements as soon as the script is evaluated. jsDelivr (https://cdn.jsdelivr.net/npm/@telperion/elements/iife/...) and other npm CDNs work the same way.

The package also declares a non-standard "script" export condition pointing at these files for tooling that wants to discover them programmatically, but no browser or major CDN currently resolves it — always use the full /iife/... path in <script src>.

📚 Components

Icon

A framework-agnostic icon element with two families: Material Symbols and Simple Icons (brand icons).

Includes:

• <tp-icon> — renders a single glyph from the chosen family

Features:

• Material Symbols: three variants (outlined, round, sharp) and all four variable-font axes exposed as attributes (filled, grade, weight, optical-size)
• Simple Icons (family="simple-icons"): brand icons (YouTube, LinkedIn, GitHub, …) loaded on demand from cdn.simpleicons.org into a single shared <svg> sprite — one HTTP request per slug, ever; auto aria-label from the brand title; tp-icon-load / tp-icon-error events; configurable base URL for self-hosting
• Light-DOM rendering so consumer styling (Tailwind, CSS variables, color/size) "just works"
• Material Symbols fonts loaded via the Google Fonts CSS API — no broken hash URLs when Google rotates them; self-host friendly

JS/TS

import "@telperion/elements/icon";

CSS

@import "@telperion/elements/icon/material-symbols.css";

HTML

<tp-icon>home</tp-icon>
<tp-icon variant="round" filled weight="700">favorite</tp-icon>
<tp-icon family="simple-icons" slug="facebook" style="color:#1877F2"></tp-icon>

Icon Documentation →

Router Components

A complete client-side routing solution for single-page applications, built with declarative web components.

Includes:

• <tha-router> - Main router component managing URL matching and navigation
• <tha-route> - Route definitions with URLPattern syntax for path matching
• <tha-router-outlet> - Content rendering outlet for active routes
• <tha-router-link> - Navigation links with automatic active state detection
• <tha-route-config> - Global router configuration

Features:

• Template-based routing without JavaScript configuration
• Multiple history strategies (browser, hash, memory)
• Dynamic route parameters and wildcards
• Relative path navigation
• Automatic active link detection
• Signal-based reactive updates

Router Documentation →

This library is actively being developed. More components will be added over time.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT © Thales RC