Sluggit

Sluggit is a lightweight TypeScript utility to convert strings into URL-friendly slugs. Removes emojis, accents, and special characters, supports custom separators, and preserves casing if needed.

This release refactors the codebase into small modules and introduces new options:

• maxLength: limit the length of the generated slug while preserving word boundaries when possible
• customReplacements: provide a mapping of characters/strings to replace before slugification
• preserveNumbers: whether numbers should be kept in the slug (default: true)
• removeTrailingDash: when true, removes any trailing separators from the final slug

Table of Contents

| Section | Description | | ------------------------------- | --------------------------------------- | | Features | Key functionality of the package | | Installation | How to install using NPM, Yarn, or PNPM | | Quick Start | Minimal example to start using Sluggit | | Usage | Full usage examples | | API Reference | Function signature and parameters | | Options | Available options and default values | | Examples | Example inputs and expected outputs |

Features

• Convert any string to a URL-friendly slug
• Remove special characters, emojis, and accents
• Customizable separator (-, _, or any character)
• Optional lowercase / uppercase
• Supports ESM and CommonJS
• TypeScript-ready with type definitions

Installation

# npm
npm install sluggit

# yarn
yarn add sluggit

# pnpm
pnpm add sluggit

Quick Start

import { sluggit } from "sluggit";

const slug = sluggit("Hello World!"); // Output: hello-world

Usage

import { sluggit } from "sluggit";

// Basic usage
sluggit("Hello World!"); // hello-world

// Custom separator
sluggit("Hello World!", { separator: "_" }); // hello_world

// Preserve case
sluggit("Hello World!", { lowercase: false }); // Hello-World

// Remove emojis
sluggit("Hello 👋 World! 🌍"); // hello-world

// Handle accents
sluggit("Hôtel Crémieux"); // hotel-cremieux

API Reference

Function Signature

function sluggit(input: string, options?: SluggitOptions): string;

Parameters

• input (string): The string to convert to a slug
• options (optional: SlugOptions): Configuration options

Return Value

• Returns a string containing the URL-friendly slug

Options

The SlugOptions interface provides the following configuration options:

interface SluggitOptions {
  separator?: string; // Default: '-'
  lowercase?: boolean; // Default: true
  trim?: boolean; // Default: true
  maxLength?: number; // Optional: max length of the slug
  customReplacements?: Record<string, string>; // Optional mappings applied before slug generation
  preserveNumbers?: boolean; // Default: true
  removeTrailingDash?: boolean; // Default: false
}

Options Description

• separator: Character to use between words (default: '-')

• lowercase: Convert the output to lowercase (default: true)

• trim: Remove leading and trailing separators (default: true)

• maxLength: When provided, the function attempts to keep whole tokens, truncating only at token boundaries when possible. If a numeric tail (e.g., a year) is present and the token before it is included in the truncated result, the numeric tail will be appended.

• customReplacements: A map of strings to replace prior to slug generation. Useful for mapping © → c, ™ → tm, & → and, etc.

• preserveNumbers: Whether numbers should be preserved (default: true). Set to false to remove all digits.

• removeTrailingDash: When true, strip trailing separators from the final slug.

Examples

Here are some example inputs and their corresponding outputs:

| Input | Options | Output | | ----------------------- | ---------------------------------------------- | ---------------------------- | | "Hello World!" | default | "hello-world" | | "Hello_World!" | { separator: '_' } | "hello_world" | | "Hello World!" | { lowercase: false } | "Hello-World" | | " Hello World! " | { trim: true } | "hello-world" | | "Café & Résumé" | { customReplacements: { "&": "and" }} | "cafe-and-resume" | | "Hello 👋 World! 🌍" | default | "hello-world" | | "Product™ & Copyright©" | { customReplacements: { "™": "tm", "©": "c" }} | "product-tm-and-copyright-c" |