DOCSEARCHbyAlgolia
Submit Docs

Telegram UI

repository·main·Indexed 21 days ago

https://github.com/telegram-mini-apps-dev/telegramui

A UI developer toolkit providing pre-designed components and tools to develop high-quality Telegram applications, including custom client apps and bots. It includes a comprehensive set of 'Blocks' for layout and structure (Accordion, Banner, Card, Cell), media and avatars, controls (Button, IconButton), and feedback components (CircularProgress, Snackbar, Spinner) to ensure consistent styling and platform-specific behavior for iOS and Android.

Tokens
13.6K
Snippets
49
Records
59
Agent score
72%

What's inside @telegram-apps/telegram-ui

  1. How the `AppRoot` theming mechanism works

    main

    The AppRoot component manages dynamic theming by combining CSS variables with React context. It automatically detects the current theme (light, dark, or Telegram custom themes) and the user's platform (iOS, Android, or web) to apply appropriate styles.

    Key behaviors include:

    • Theme Detection: Updates CSS variables based on Telegram settings or manual preferences.
    • Platform Adaptation: Applies platform-specific styles (typography, sizing, interaction feedback) to match platform conventions.
    • Contextual Access: Uses React context to provide theme and platform information to all nested components, enabling conditional rendering or styling deep within the component tree.

  2. Understand Basic vs Custom CSS Variables in `AppRoot`

    main

    The AppRoot theming system relies on two categories of CSS variables to manage appearance:

    Basic Variables

    Used for inheriting styles directly from Telegram or falling back to library defaults.

    • Telegram Style Inheritance: Dynamically adopts values from the user's Telegram theme.
    • Library Defaults: Used when Telegram theme data is unavailable or unsupported, ensuring a coherent interface.

    Custom Variables

    Used for extending the theme beyond Telegram's native capabilities.

    • Enhanced Styling: Allows defining unique elements like specific accent colors.
    • Brand Identity: Enables developers to align the application with a specific brand through custom colors and typography while still respecting the underlying theme structure.

  3. Set up Telegram UI in your application

    main

    To use Telegram UI components, you must perform two setup steps:

    1. Import Styles: Import the global CSS file at the entry point of your application to ensure all components are styled correctly.
    2. Wrap Your App: Wrap your top-level application component with the AppRoot component to enable platform-specific features and correct layout behavior.
    // 1. Import styles
import '@telegram-apps/telegram-ui/dist/styles.css';

// 2. Wrap your app
import { AppRoot } from '@telegram-apps/telegram-ui';
import ReactDOM from 'react-dom';

ReactDOM.render(
  <AppRoot>
    <App />
  </AppRoot>,
  document.getElementById('root')
);

  7. Configure biometric authentication in PinInput

    main

    You can display a biometric authentication button within the PinInput keypad by providing the biometricType prop. If biometricType is undefined, no biometric button will be shown. Use the onBiometricAuth callback to handle the authentication trigger.

    <PinInput
  biometricType="FACEID" // or "FINGERPRINT"
  onBiometricAuth={() => handleBiometricAuth()}
/>

  8. Use Telegram UI in your application

    main

    To use the library, you must first import the required CSS styles. Wrap your application in the AppRoot component to ensure consistent styling and platform-specific behavior (iOS/Android). You can then use various components like Placeholder to build your UI.

    import '@telegram-apps/telegram-ui/dist/styles.css';

import { AppRoot, Placeholder } from '@telegram-apps/telegram-ui';

const App = () => (
  <AppRoot>
    <Placeholder
      header="Title"
      description="Description"
    >
      <img
        alt="Telegram sticker"
        src="https://xelene.me/telegram.gif"
        style={{ display: 'block', width: '144px', height: '144px' }}
      />
    </Placeholder>
  </AppRoot>
);

export default App;

  9. Use List, Section, and Cell components

    main

    Telegram UI provides structured components for building lists. You can use List as a container, Section to group items with optional headers and footers, and Cell to render individual items within a section. All these components should be wrapped inside an AppRoot.

    // Import the necessary styles globally
import '@telegram-apps/telegram-ui/dist/styles.css';

// Import components from the library
import { AppRoot, Cell, List, Section } from '@telegram-apps/telegram-ui';

// Example data for rendering list cells
const cellsTexts = ['Chat Settings', 'Data and Storage', 'Devices'];

export const App = () => (
  <AppRoot>
    {/* List component to display a collection of items */}
    <List>
      {/* Section component to group items within the list */}
      <Section header="Header for the section" footer="Footer for the section">
        {/* Mapping through the cells data to render Cell components */}
        {cellsTexts.map((cellText, index) => (
          <Cell key={index}>
            {cellText}
          </Cell>
        ))}
      </Section>
    </List>
  </AppRoot>
);

  10. Import components from @telegram-apps/telegram-ui

    main

    The @telegram-apps/telegram-ui package provides a comprehensive set of UI components organized into functional modules. You can import components directly from the main entrypoint. The library is categorized into the following modules:

    • Blocks: Layout and structural components.
    • Feedback: Components for user feedback (e.g., toasts, loaders).
    • Form: Input and form-related components.
    • Layout: Structural layout components.
    • Misc: Miscellaneous utility components.
    • Navigation: Navigation-related components (e.g., tabs, menus).
    • Overlays: Components that appear on top of other content (e.g., modals, popups).
    • Service: Service-related components or logic.
    • Typography: Text and typography components.
    import {
  Button,
  TextInput,
  Modal,
  Text,
  // ... other components
} from '@telegram-apps/telegram-ui';

  12. Use the Banner component

    main

    The Banner component renders a prominent graphical element designed to grab attention for branding, promotions, announcements, or navigation. It supports various layouts, background decorations, and a close action.

    Props

    PropTypeDescription
    type'section' | 'inline'Specifies the layout style, affecting positioning and styling.
    beforeReactNodeElement(s) placed on the left side (e.g., an icon or image).
    calloutReactNodeContent displayed as a subheading above the main header.
    headerReactNodeThe main text or title.
    subheaderReactNodeAdditional information displayed below the header.
    descriptionReactNodeFurther details or subtext displayed below the subheader.
    backgroundReactNodeA custom background component (image, gradient, etc.) that covers the banner area.
    onCloseIconMouseEventHandler<HTMLButtonElement>Callback executed when the close icon is clicked. If omitted, the close icon is not rendered.
    childrenReactNodeContent (like buttons) displayed within the banner's action area.
    classNamestringAdditional CSS classes for the wrapper.
    ...restPropsHTMLAttributes<HTMLDivElement>Standard HTML attributes for the underlying section element.
    import { Banner } from '@telegram-apps/telegram-ui';

function MyComponent() {
  return (
    <Banner
      header="Welcome!"
      subheader="Check out our new features."
      description="We have updated the interface for a better experience."
      onCloseIcon={() => console.log('Banner closed')}
    >
      <button>Get Started</button>
    </Banner>
  );
}