DEV Community

Cover image for React component for Telegram Login Widget
advanceddev
advanceddev

Posted on

React component for Telegram Login Widget

#react #telegram #typescript #security

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"
/>
Enter fullscreen mode Exit fullscreen mode

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;
}
Enter fullscreen mode Exit fullscreen mode

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>
  );
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

or

yarn add @advanceddev/telegram-login-react
Enter fullscreen mode Exit fullscreen mode 
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"
  />
);
Enter fullscreen mode Exit fullscreen mode

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

Top comments (0)