React component for Telegram Login Widget

advanceddev — Fri, 23 Jan 2026 07:41:00 +0000

After struggling with fragmented, outdated solutions for Telegram Login integration in React projects, I built @advanceddev/telegram-login-react – a modern, type-safe component that just works with React 18+, Next.js App Router, and TypeScript.

Why Another Library?

The official Telegram Login Widget is powerful but needed a solution that was:

✅ Type-safe (full TypeScript support)
✅ Framework-agnostic (works with Vite, CRA, Next.js)
✅ Secure by default (enforces server-side hash validation)
✅ Lightweight (~9kB minified, zero dependencies)
✅ Production-ready (with proper cleanup and error handling)

Key Features

1. Dual Authentication Modes

// Callback mode (client-side handling)
<TelegramLoginButton
  botUsername="my_bot"
  onAuthCallback={(user) => {
    // Send user data to your backend for hash validation
    validateUser(user);
  }}
/>

// Redirect mode (server-side handling)
<TelegramLoginButton
  botUsername="my_bot"
  authUrl="https://myapp.com/api/auth/telegram"
/>

2. Full TypeScript Support

interface TelegramLoginWidgetData {
  id: number;
  first_name: string;
  last_name?: string;
  username?: string;
  photo_url?: string;
  auth_date: number;
  hash: string; // Critical for server validation!
}

interface TelegramLoginButtonBaseProps {
    botUsername: string;
    onAuthCallback?: (data: TelegramLoginWidgetData) => void;
    authUrl?: string;
    requestAccess?: 'write' | 'read';
    cornerRadius?: number;
    widgetVersion?: number;
    size?: 'large' | 'medium' | 'small';
    radius?: string | number;
    userPic?: boolean;
    lang?: 'en' | 'ru' | 'uk' | 'de' | 'it' | 'es' | 'pt' | 'tr' | 'fa' | 'ar';
    className?: string;
    children?: React.ReactNode;
}

3. Next.js App Router Ready

The component is fully compatible with Next.js 13+ App Router out of the box. It uses the 'use client' directive internally, so you can import and use it directly in your components without any additional configuration.

Checking for typeof window === 'undefined' before executing browser-only code
Using React's useEffect for DOM manipulation (which only runs on the client)
Properly cleaning up global event handlers to prevent memory leaks

// app/page.tsx
import { TelegramLoginButton } from '@advanceddev/telegram-login-react
';

export default function LoginPage() {
  return (
    <div>
      <h1>Login with Telegram</h1>
      <TelegramLoginButton
        botUsername="my_bot"
        onAuthCallback={(user) => console.log(user)}
      />
    </div>
  );
}

4. Security-First Design

Enforces server-side hash validation (never validate on client!)
Clear documentation about security best practices
Automatic cleanup to prevent memory leaks

Getting Started

npm install @advanceddev/telegram-login-react

yarn add @advanceddev/telegram-login-react

import { TelegramLoginButton } from '@advanceddev/telegram-login-react';

const App = () => (
  <TelegramLoginButton
    botUsername="your_bot_username"
    onAuthCallback={(user) => {
      // ⚠️ Always validate 'hash' on your server!
      fetch('/api/validate-telegram', {
        method: 'POST',
        body: JSON.stringify(user)
      });
    }}
    size="large"
    lang="en"
  />
);

Important Security Note

Never validate the hash parameter on the client!
Always send the complete user object to your backend and validate it using your bot's secret token. The package includes clear documentation about this critical security practice.

Technical Details

Bundle size: ~9kB (minified + gzipped)
Dependencies: Zero runtime dependencies (only peer deps on React)
Tree-shakeable: Unused modes won't be included in your bundle
CSP compliant: Works with modern Content Security Policies

Try It Out

NPM Package
GitHub Repository

Feedback Wanted!

Are there features you'd like to see?
Any issues with your specific setup?
Suggestions for improvement?

Star the repo if you find it useful! ⭐

Built with ❤️ for the React community

Product Card with gallery (ReactJS)

advanceddev — Tue, 30 Apr 2019 05:25:25 +0000

Карточка товара с галереей для ReactJS.

Comments (ReactJS + Foundation CSS)

advanceddev — Mon, 29 Apr 2019 19:27:01 +0000

Post comment system for ReactJS (using Foundation CSS)

DEV Community: advanceddev