@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

npm install @telegram.ts/formatters

yarn add @telegram.ts/formatters

pnpm add @telegram.ts/formatters

🚀 Quick Start

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

HTML Formatting

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

// Basic formatting
html.bold("Bold text"); // <b>Bold text</b>
html.italic("Italic text"); // <i>Italic text</i>
html.underline("Underlined"); // <u>Underlined</u>
html.strikethrough("Strikethrough"); // <s>Strikethrough</s>
html.spoiler("Spoiler text"); // <span class="tg-spoiler">Spoiler text</span>

// Links and mentions
html.inlineURL("Google", "https://google.com");
// <a href="https://google.com">Google</a>

html.inlineMention("John", 123456789);
// <a href="tg://user?id=123456789">John</a>

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

html.codeBlock("const x = 1;\nconsole.log(x);", "javascript");
// <pre><code class="language-javascript">const x = 1;
// console.log(x);</code></pre>

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

html.expandableBlockquote("Long quote...");
// <blockquote expandable>Long quote...</blockquote>

// Custom emoji
html.inlineEmoji("👍", "5368324170671202286");
// <tg-emoji emoji-id="5368324170671202286">👍</tg-emoji>

MarkdownV2 Formatting

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](https://google.com)

markdownv2.inlineMention("John", 123456789);
// [John](tg://user?id=123456789)

// 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");
// ![👍](tg://emoji?id=5368324170671202286)

Combining Formats

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

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

// 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

Working with Entities

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");

Utilities

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

// Escape special characters
escapeHTML("<script>alert('XSS')</script>");
// &lt;script&gt;alert(&#39;XSS&#39;)&lt;/script&gt;

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

// Strip HTML tags
stripHTML("<b>Bold</b> text");
// Bold text

// Get text length without formatting
getTextLength("<b>Hello</b>", "HTML");
// 5

🎯 Real-World Examples

Profile Card

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",
  );
}

Menu with Buttons

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",
  );
}

Code Example

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",
);

Progress Bar

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",
  );
}

Error Message

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

HTML Formatter

| Function | Description | Example | | ----------------------------- | ------------------ | ------------------------------------------ | | bold(text) | Bold text | <b>text</b> | | italic(text) | Italic text | <i>text</i> | | underline(text) | Underlined text | <u>text</u> | | strikethrough(text) | Strikethrough text | <s>text</s> | | spoiler(text) | Spoiler text | <span class="tg-spoiler">text</span> | | blockquote(text) | Block quote | <blockquote>text</blockquote> | | expandableBlockquote(text) | Expandable quote | <blockquote expandable>text</blockquote> | | inlineURL(text, url) | Inline link | <a href="url">text</a> | | inlineMention(text, userId) | User mention | <a href="tg://user?id=123">text</a> | | inlineCode(text) | Inline code | <code>text</code> | | codeBlock(text, lang?) | Code block | <pre><code>text</code></pre> | | inlineEmoji(emoji, id) | Custom emoji | <tg-emoji emoji-id="id">emoji</tg-emoji> | | combine(parts, sep?) | Combine strings | Joins array with separator | | list(items, ordered?) | Create list | Formats array as list |

MarkdownV2 Formatter

| 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](url) | | inlineMention(text, userId) | User mention | [text](tg://user?id=123) | | inlineCode(text) | Inline code | `text` | | codeBlock(text, lang?) | Code block | ```lang\ntext\n``` | | inlineEmoji(emoji, id) | Custom emoji | ![emoji](tg://emoji?id=id) |

Utilities

| 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 |

Parser Functions

| 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

With TelegramsJS

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();

With node-telegram-bot-api

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" });
});

With Telegraf

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