@baranov-guru/react-telegram-widgets

@baranov-guru/react-telegram-widgets

React components for embedding Telegram posts and comments widgets in your web applications.

📖 Official Documentation: This package is based on the Telegram Widget API. For detailed information about widget configuration and options, please refer to the official documentation.

Installation

npm install @baranov-guru/react-telegram-widgets

or

yarn add @baranov-guru/react-telegram-widgets

Usage

TelegramPostWidget

Embed a Telegram post in your React application:

import { TelegramPostWidget } from '@baranov-guru/react-telegram-widgets';

function App() {
  return (
    <div>
      <h1>My Blog Post</h1>
      <p>Check out this Telegram post:</p>
      <TelegramPostWidget
        post='alexey_baranov_dev/61'
        width='100%'
        dark={true}
        onLoad={() => console.log('Post loaded successfully!')}
        onError={error => console.error('Failed to load post:', error)}
      />
    </div>
  );
}

TelegramDiscussionWidget

Embed Telegram comments for a discussion:

import { TelegramDiscussionWidget } from '@baranov-guru/react-telegram-widgets';

function App() {
  return (
    <div>
      <h1>Discussion</h1>
      <TelegramDiscussionWidget
        discussion='alexey_baranov_dev/61'
        commentsLimit={10}
        height={400}
        color='#ff0000'
        colorful={true}
        dark={true}
        onLoad={() => console.log('Comments loaded!')}
        onError={error => console.error('Failed to load comments:', error)}
      />
    </div>
  );
}

API Reference

TelegramPostWidget Props

Prop	Type	Default	Description
post	string	required	The post identifier in format "channel/post_id" (e.g., "alexey_baranov_dev/1")
userpic	boolean | "auto"	"auto"	Whether to show user pictures. "auto" shows them only if post contains them
width	CSSProperties["width"] | "100%"	"100%"	The width of the widget
dark	boolean	false	Enable dark theme
className	string	-	Optional CSS class for the container
onError	(e: unknown) => void	-	Callback when an error occurs
onLoad	() => void	-	Callback when the widget loads successfully

TelegramDiscussionWidget Props

Prop	Type	Default	Description
discussion	string	required	The discussion identifier in format "channel/post_id" or just "channel" (e.g., "alexey_baranov_dev/1" or "alexey_baranov_dev")
commentsLimit	number	5	Maximum number of comments to display
height	number	-	Height of the widget in pixels
color	string	-	Color of widget elements (hex format, e.g., "#cbcbcb")
colorful	boolean	false	Enable colorful usernames
dark	boolean	false	Enable dark theme
className	string	-	Optional CSS class for the container
onError	(e: unknown) => void	-	Callback when an error occurs
onLoad	() => void	-	Callback when the widget loads successfully

Examples

Basic Usage

import {
  TelegramPostWidget,
  TelegramDiscussionWidget,
} from '@baranov-guru/react-telegram-widgets';

function BlogPost() {
  return (
    <article>
      <h1>My Article</h1>
      <p>Article content...</p>

      {/* Embed a related Telegram post */}
      <TelegramPostWidget
        post='alexey_baranov_dev/1'
        width='100%'
        dark={true}
      />

      {/* Add comments section */}
      <h2>Comments</h2>
      <TelegramDiscussionWidget
        discussion='alexey_baranov_dev'
        commentsLimit={20}
        height={500}
        colorful={true}
      />
    </article>
  );
}

With Error Handling

import { TelegramPostWidget } from '@baranov-guru/react-telegram-widgets';

function SafeTelegramWidget() {
  const handleError = (error: unknown) => {
    console.error('Telegram widget error:', error);
    // Show fallback content or error message
  };

  const handleSuccess = () => {
    console.log('Telegram widget loaded successfully');
  };

  return (
    <TelegramPostWidget
      post='alexey_baranov_dev/61'
      onError={handleError}
      onLoad={handleSuccess}
    />
  );
}

Custom Styling

import { TelegramDiscussionWidget } from '@baranov-guru/react-telegram-widgets';

function CustomComments() {
  return (
    <TelegramDiscussionWidget
      discussion='alexey_baranov_dev/61'
      commentsLimit={15}
      height={600}
      color='#4a90e2'
      colorful={true}
      dark={true}
      className='my-custom-comments-widget'
    />
  );
}

TypeScript Support

The package includes full TypeScript support with exported types:

import {
  TelegramPostWidget,
  TelegramPostWidgetProps,
  TelegramDiscussionWidget,
  TelegramDiscussionWidgetProps,
} from '@baranov-guru/react-telegram-widgets';

// Use the types for your own components
const MyComponent: React.FC<TelegramPostWidgetProps> = props => {
  return <TelegramPostWidget {...props} />;
};

Requirements

• React 16.8.0 or higher
• React DOM 16.8.0 or higher

Browser Support

This package uses the official Telegram Widget API, which supports all modern browsers.

Author

Alexey Baranov (Nejivoi)

• GitHub: @Nejivoi
• Website: alexeybaranov.dev

Support the Author

If you find this package helpful and would like to support its development, please consider:

Your support helps maintain and improve this package! ❤️

License

MIT

Contributing

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

Publishing

This package uses GitHub Actions for automated publishing. To publish a new version:

• Set up NPM Token: Add your NPM token as a GitHub secret named NPM_TOKEN

  • Go to your GitHub repository settings
  • Navigate to Secrets and variables → Actions
  • Add a new secret with name NPM_TOKEN and your NPM access token as the value

• Create a Release:

  • Create a new release on GitHub
  • Tag it with the version (e.g., v1.0.1)
  • The workflow will automatically build, test, and publish to npm

Manual Publishing

If you prefer to publish manually:

npm run build
npm publish --access public

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build package
npm run build

# Watch mode for development
npm run dev

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Check code formatting
npm run format:check

# Run all checks (lint, format, test)
npm run check