use-telegram

A TypeScript package for easy integration with Telegram WebApp API. Provides React hooks and context for managing Telegram WebApp's MainButton with full TypeScript support.

Features

• 🚀 React Hooks: Easy-to-use hooks for Telegram WebApp integration
• 📝 TypeScript: Full TypeScript support with proper type definitions
• 🎯 Flexible: Support for both persistent and one-time action buttons
• 🔄 Auto-updates: Button text and options update automatically on state changes
• 🎯 Flexible: Support for both persistent and one-time action buttons

Installation

npm install use-telegram

Quick Start

1. Wrap your app with the provider

import { TelegramWebContextProvider } from 'use-telegram';

function App() {
  return (
    <TelegramWebContextProvider>
      <YourApp />
    </TelegramWebContextProvider>
  );
}

2. Use the hooks in your components

import { useMainButton, useActionButton } from 'use-telegram';

function MyComponent() {
  const [count, setCount] = useState(0);

  // Persistent button that stays visible
  const counterBtn = useMainButton(
    { text: `Counter ${count}`, hasShineEffect: true }, 
    (btn) => {
      setCount(prev => {
        const newCount = prev + 1;
        btn.setText(`Counter ${newCount}`);
        return newCount;
      });
    }
  );

  // One-time button that hides after click
  const oneTimeBtn = useActionButton(
    { text: 'One time button', hasShineEffect: true }, 
    () => {
      alert('One time button clicked');
    }
  );

  return (
    <div>
      <button onClick={counterBtn.showButton}>Show Counter Button</button>
      <button onClick={oneTimeBtn.showButton}>Show One-time Button</button>
      <button onClick={counterBtn.hideButton}>Hide Button</button>
    </div>
  );
}

API Reference

Hooks

useMainButton(options, onClick?)

Creates a persistent main button that stays visible until manually hidden.

Parameters:

• options (Partial): Button configuration
• onClick? (btn: MainButton) => void: Click handler with button instance

Returns:

• showButton(): Function to show the button
• hideButton(): Function to hide the button

useActionButton(options, onClick?)

Creates a one-time action button that automatically hides after being clicked.

Parameters:

• options (Partial): Button configuration
• onClick? (btn: MainButton) => void: Click handler with button instance

Returns:

• showButton(): Function to show the button
• hideButton(): Function to hide the button

Button Options

interface MainButton {
  text: string;           // Button text
  color?: string;         // Button color (hex format)
  hasShineEffect?: boolean; // Enable shine effect
}

Context Provider

TelegramWebContextProvider

Wraps your app to provide Telegram WebApp functionality.

Props:

• children: React components
• theme?: Optional theme parameters

<TelegramWebContextProvider theme={{ bg_color: '#ffffff' }}>
  {children}
</TelegramWebContextProvider>

Examples

Counter with Auto-updating Text

import { useState } from 'react';
import { useMainButton } from 'use-telegram';

function Counter() {
  const [count, setCount] = useState(0);

  const btn = useMainButton(
    { text: `Count: ${count}`, hasShineEffect: true },
    (btn) => {
      setCount(prev => {
        const newCount = prev + 1;
        btn.setText(`Count: ${newCount}`);
        return newCount;
      });
    }
  );

  return (
    <div>
      <p>Current count: {count}</p>
      <button onClick={btn.showButton}>Show Counter Button</button>
      <button onClick={btn.hideButton}>Hide Button</button>
    </div>
  );
}

Form Submission

import { useActionButton } from 'use-telegram';

function Form() {
  const [formData, setFormData] = useState('');

  const submitBtn = useActionButton(
    { text: 'Submit Form', color: '#007AFF' },
    () => {
      // Form will be submitted and button will auto-hide
      console.log('Form submitted:', formData);
    }
  );

  return (
    <div>
      <input 
        value={formData} 
        onChange={(e) => setFormData(e.target.value)}
        placeholder="Enter data"
      />
      <button onClick={submitBtn.showButton}>Show Submit Button</button>
    </div>
  );
}

Custom Theme

import { TelegramWebContextProvider } from 'use-telegram';

function App() {
  const theme = {
    bg_color: '#ffffff',
    text_color: '#000000',
    hint_color: '#999999',
    link_color: '#007AFF',
    button_color: '#007AFF',
    button_text_color: '#ffffff'
  };

  return (
    <TelegramWebContextProvider theme={theme}>
      <YourApp />
    </TelegramWebContextProvider>
  );
}

Requirements

• React 18+
• Node.js 16+
• Telegram WebApp environment

Browser Support

This package is designed to work within Telegram's WebApp environment. Make sure your app is running inside Telegram's WebApp container.

Development

# Install dependencies
npm install

# Build the package
npm run build

# Watch for changes
npm run dev

# Lint code
npm run lint

# Format code
npm run format

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you encounter any issues or have questions, please open an issue on GitHub.

Changelog

1.0.0

• Initial release
• Support for MainButton and ActionButton hooks
• Theme customization
• Full TypeScript support