@telegram.ts/formatters


Powerful and type-safe text formatting library for Telegram Bot API with full HTML and MarkdownV2 support.

✨ Features

- 🎨 Multiple Format Support - HTML, MarkdownV2, and legacy Markdown
- 🔒 Type-Safe - Full TypeScript support with comprehensive type definitions
- 🛡️ Auto-Escaping - Automatic escaping of special characters
- 🎯 Simple API - Intuitive and easy-to-use formatting functions
- 📦 Zero Dependencies - Lightweight with no external dependencies
- 🔧 Flexible - Works with any Telegram bot library
- ⚡ Fast - Optimized for performance
- 📚 Well-Documented - Extensive documentation and examples

📦 Installation

``bash
npm install @telegram.ts/formatters
`

`bash
yarn add @telegram.ts/formatters
`

`bash
pnpm add @telegram.ts/formatters
`

🚀 Quick Start

`typescript
import { html, markdownv2 } from "@telegram.ts/formatters";

// HTML formatting
const htmlText =
html.bold("Bold text") +
"\n" +
html.italic("Italic text") +
"\n" +
html.underline("Underlined text") +
"\n" +
html.inlineURL("Click here", "https://example.com");

// MarkdownV2 formatting
const markdownText =
markdownv2.bold("Bold text") +
"\n" +
markdownv2.italic("Italic text") +
"\n" +
markdownv2.strikethrough("Strikethrough text");

// Send with your bot library
await bot.sendMessage(chatId, htmlText, { parse_mode: "HTML" });
await bot.sendMessage(chatId, markdownText, { parse_mode: "MarkdownV2" });
`

📖 Usage

$3

`typescript
import { html } from "@telegram.ts/formatters";

// Basic formatting
html.bold("Bold text"); // Bold text
html.italic("Italic text"); // Italic text
html.underline("Underlined"); // Underlined
html.strikethrough("Strikethrough"); // Strikethrough
html.spoiler("Spoiler text"); // Spoiler text

// Links and mentions
html.inlineURL("Google", "https://google.com");
// Google

html.inlineMention("John", 123456789);
// John

// Code
html.inlineCode("const x = 1");
// const x = 1

html.codeBlock("const x = 1;\nconsole.log(x);", "javascript");
//

const x = 1;
// console.log(x);

// Quotes
html.blockquote("This is a quote");
//

This is a quote

html.expandableBlockquote("Long quote...");
//

Long quote...

// Custom emoji
html.inlineEmoji("👍", "5368324170671202286");
// 👍
`

$3

``typescript
import { markdownv2 } from "@telegram.ts/formatters";

// Basic formatting
markdownv2.bold("Bold text"); // Bold text
markdownv2.italic("Italic text"); // _Italic text_
markdownv2.underline("Underlined"); // __Underlined__
markdownv2.strikethrough("Strike"); // ~Strike~
markdownv2.spoiler("Spoiler"); // ||Spoiler||

// Links and mentions
markdownv2.inlineURL("Google", "https://google.com");
// Google

markdownv2.inlineMention("John", 123456789);
// John

// Code
markdownv2.inlineCode("const x = 1");
// const x = 1

markdownv2.codeBlock("const x = 1;", "javascript");
// `javascript
// const x = 1;
// `

// Quotes
markdownv2.blockquote("Quote"); // >Quote
markdownv2.expandableBlockquote("Long"); // **>Long

// Custom emoji
markdownv2.inlineEmoji("👍", "5368324170671202286");
// !👍
``

$3

`typescript
import { html } from "@telegram.ts/formatters";

// Combine multiple formats
const text = html.combine([html.bold("Hello"), html.italic("World")], " ");
// Hello World

// Create lists
const list = html.list(["First item", "Second item", "Third item"], true); // true for ordered list
// 1. First item
// 2. Second item
// 3. Third item
`

$3

`typescript
import { parseEntities, entitiesToFormatted } from "@telegram.ts/formatters";

// Parse formatted text to entities
const text = html.bold("Hello") + " " + html.italic("World");
const entities = parseEntities(text, "HTML");

// Convert entities back to formatted text
const formattedText = entitiesToFormatted("Hello World", entities, "HTML");
`

$3

`typescript
import {
escapeHTML,
escapeMarkdownV2,
stripHTML,
getTextLength,
} from "@telegram.ts/formatters";

// Escape special characters
escapeHTML("");
// <script>alert('XSS')</script>

escapeMarkdownV2("Text with special chars");
// Text with \\special\\ chars

// Strip HTML tags
stripHTML("Bold text");
// Bold text

// Get text length without formatting
getTextLength("Hello", "HTML");
// 5
`

🎯 Real-World Examples

$3

`typescript
import { html } from "@telegram.ts/formatters";

function createProfile(user: User) {
return html.combine(
[
html.bold("👤 USER PROFILE"),
html.strikethrough("━━━━━━━━━━━━━━━━"),
"",
html.bold("Name: ") + html.italic(user.firstName),
html.bold("ID: ") + html.inlineCode(user.id.toString()),
html.bold("Username: ") +
(user.username ? @${user.username} : html.italic("not set")),
html.bold("Status: ") + html.underline("Active"),
],
"\n",
);
}
`

$3

`typescript
import { html } from "@telegram.ts/formatters";

function createMenu() {
return html.combine(
[
html.bold("🎮 MAIN MENU"),
html.strikethrough("━━━━━━━━━━━━━"),
"",
html.bold("1. ") + html.underline("Profile") + " 👤",
html.bold("2. ") + html.underline("Settings") + " ⚙️",
html.bold("3. ") + html.underline("Help") + " ❓",
"",
html.italic("Choose an option"),
],
"\n",
);
}
`

$3

`typescript
import { html } from "@telegram.ts/formatters";

const code =
import { TelegramClient } from "telegramsjs";

const client = new TelegramClient("TOKEN");

client.on("ready", () => {
console.log("Bot is ready!");
});

client.login();
;

const message = html.combine(
[
html.bold("📝 Example Code"),
"",
html.codeBlock(code.trim(), "typescript"),
"",
html.italic("Copy and paste to get started!"),
],
"\n",
);
`

$3

`typescript
import { html } from "@telegram.ts/formatters";

function createProgress(percentage: number) {
const filled = Math.floor(percentage / 10);
const empty = 10 - filled;
const bar = "█".repeat(filled) + "░".repeat(empty);

return html.combine(
[
html.bold("📊 Download Progress"),
"",
html.inlineCode(bar) + " " + html.bold(${percentage}%),
"",
html.italic("Status: ") + html.underline("In progress..."),
],
"\n",
);
}
`

$3

`typescript
import { html } from "@telegram.ts/formatters";

function createError(error: Error) {
return html.combine(
[
html.bold("❌ ERROR"),
html.strikethrough("━━━━━━━━━━"),
"",
html.italic("An error occurred:"),
"",
html.codeBlock(error.message, "text"),
"",
html.underline("Please try again later"),
],
"\n",
);
}
`

📚 API Reference

$3

| Function | Description | Example |
| ----------------------------- | ------------------ | ------------------------------------------ |
| bold(text) | Bold text | text |
| italic(text) | Italic text | text |
| underline(text) | Underlined text | text |
| strikethrough(text) | Strikethrough text | text |
| spoiler(text) | Spoiler text | text |
| blockquote(text) | Block quote |

text

|
| expandableBlockquote(text) | Expandable quote |

text

|
| inlineURL(text, url) | Inline link | text |
| inlineMention(text, userId) | User mention | text |
| inlineCode(text) | Inline code | text |
| codeBlock(text, lang?) | Code block |

text

|
| inlineEmoji(emoji, id) | Custom emoji | emoji |
| combine(parts, sep?) | Combine strings | Joins array with separator |
| list(items, ordered?) | Create list | Formats array as list |

$3

| Function | Description | Example |
| ----------------------------- | ------------------ | ---------------------------- |
| bold(text) | Bold text | text |
| italic(text) | Italic text | _text_ |
| underline(text) | Underlined text | __text__ |
| strikethrough(text) | Strikethrough text | ~text~ |
| spoiler(text) | Spoiler text | \|\|text\|\| |
| blockquote(text) | Block quote | >text |
| expandableBlockquote(text) | Expandable quote | **>text |
| inlineURL(text, url) | Inline link | text |
| inlineMention(text, userId) | User mention | text |
| inlineCode(text) | Inline code | text |
| codeBlock(text, lang?) | Code block | ``lang\ntext\n` |
| inlineEmoji(emoji, id) | Custom emoji | !emoji |

$3

| Function | Description |
| --------------------------- | ------------------------------------ |
| escapeHTML(text) | Escape HTML special characters |
| escapeMarkdownV2(text) | Escape MarkdownV2 special characters |
| escapeMarkdown(text) | Escape Markdown special characters |
| stripHTML(text) | Remove HTML tags from text |
| getTextLength(text, mode) | Get text length without formatting |

$3

| Function | Description |
| ------------------------------------------- | ---------------------------------- |
| parseEntities(text, mode) | Parse formatted text to entities |
| entitiesToFormatted(text, entities, mode) | Convert entities to formatted text |
| calculateOffset(text, position) | Calculate offset in plain text |
| mergeEntities(entities) | Merge overlapping entities |

🔧 Integration Examples

$3

``typescript
import { TelegramClient } from "telegramsjs";
import { html } from "@telegram.ts/formatters";

const client = new TelegramClient("YOUR_BOT_TOKEN");

client.on("message", async (message) => {
if (message.content === "/start") {
const text = html.combine(
[
html.bold("Welcome!"),
html.italic("I'm a bot with beautiful formatting"),
],
"\n",
);

await message.reply(text, { parse_mode: "HTML" });
}
});

client.login();
`

$3

`typescript
import TelegramBot from "node-telegram-bot-api";
import { html } from "@telegram.ts/formatters";

const bot = new TelegramBot("YOUR_BOT_TOKEN", { polling: true });

bot.onText(/\/start/, (msg) => {
const text = html.bold("Hello!") + "\n" + html.italic("Welcome to the bot");

bot.sendMessage(msg.chat.id, text, { parse_mode: "HTML" });
});
`

$3

`typescript
import { Telegraf } from "telegraf";
import { html } from "@telegram.ts/formatters";

const bot = new Telegraf("YOUR_BOT_TOKEN");

bot.start((ctx) => {
const text = html.bold("Hello!") + "\n" + html.italic("Welcome!");

ctx.reply(text, { parse_mode: "HTML" });
});

bot.launch();
`

🎓 Best Practices

1. Choose the right format: HTML is recommended for most cases as it's easier to work with
2. Use auto-escaping: The library automatically escapes special characters, so you don't need to worry about it
3. Combine wisely: Use combine()` for cleaner code when joining multiple formatted strings
4. Cache formatted text: For frequently used messages, cache the formatted text to improve performance
5. Test with Telegram: Always test your formatted messages in Telegram to ensure they render correctly

🤝 Contributing

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

🔗 Links

- NPM Package
- GitHub Repository
- Telegram Bot API
- TelegramsJS Documentation