Theme & Appearance

Mini Apps support automatic adaptation to the user's light/dark theme and provide rich theme color parameters and CSS variables.

ThemeParams

The ThemeParams object contains the color parameters of the client's current theme. Accessed via Telegram.WebApp.themeParams.

Color Properties

Property	Type	Description
bg_color	String	Background color
text_color	String	Primary text color
hint_color	String	Hint text color
link_color	String	Link color
button_color	String	Button background color
button_text_color	String	Button text color
secondary_bg_color	String	Secondary background color
header_bg_color	String	Header bar background color. Bot API 7.10+
bottom_bar_bg_color	String	Bottom bar background color. Bot API 7.10+
accent_text_color	String	Accent text color. Bot API 7.10+
section_bg_color	String	Section background color. Bot API 7.10+
section_header_text_color	String	Section header text color. Bot API 7.10+
section_separator_color	String	Section separator color. Bot API 7.10+
subtitle_text_color	String	Subtitle text color. Bot API 7.10+
destructive_text_color	String	Destructive action text color. Bot API 7.10+

CSS Variables

The Mini App SDK automatically injects all theme colors as CSS variables, which can be used directly in stylesheets:

.my-element {
  background-color: var(--tg-theme-bg-color);
  color: var(--tg-theme-text-color);
}

.my-button {
  background-color: var(--tg-theme-button-color);
  color: var(--tg-theme-button-text-color);
}

.my-link {
  color: var(--tg-theme-link-color);
}

.my-hint {
  color: var(--tg-theme-hint-color);
}

Full CSS variable list:

CSS Variable	Corresponding Property
--tg-theme-bg-color	bg_color
--tg-theme-text-color	text_color
--tg-theme-hint-color	hint_color
--tg-theme-link-color	link_color
--tg-theme-button-color	button_color
--tg-theme-button-text-color	button_text_color
--tg-theme-secondary-bg-color	secondary_bg_color
--tg-theme-header-bg-color	header_bg_color
--tg-theme-bottom-bar-bg-color	bottom_bar_bg_color
--tg-theme-accent-text-color	accent_text_color
--tg-theme-section-bg-color	section_bg_color
--tg-theme-section-header-text-color	section_header_text_color
--tg-theme-section-separator-color	section_separator_color
--tg-theme-subtitle-text-color	subtitle_text_color
--tg-theme-destructive-text-color	destructive_text_color

Listening for Theme Changes

Telegram.WebApp.onEvent('themeChanged', () => {
  const theme = Telegram.WebApp.themeParams;
  console.log('Background color:', theme.bg_color);
  console.log('Theme mode:', Telegram.WebApp.colorScheme);
});

SafeAreaInset

The SafeAreaInset object describes the device safe area insets (such as notch and rounded corner areas). Accessed via Telegram.WebApp.safeAreaInset. Bot API 8.0+

Property	Type	Description
top	Integer	Top safe area inset in pixels
bottom	Integer	Bottom safe area inset in pixels
left	Integer	Left safe area inset in pixels
right	Integer	Right safe area inset in pixels

Example

const inset = Telegram.WebApp.safeAreaInset;
document.body.style.paddingTop = inset.top + 'px';
document.body.style.paddingBottom = inset.bottom + 'px';

ContentSafeAreaInset

The ContentSafeAreaInset object describes the content safe area insets (excluding space occupied by the Mini App's own UI elements). Accessed via Telegram.WebApp.contentSafeAreaInset. Bot API 8.0+

Property	Type	Description
top	Integer	Top content safe area inset in pixels
bottom	Integer	Bottom content safe area inset in pixels
left	Integer	Left content safe area inset in pixels
right	Integer	Right content safe area inset in pixels

Example

const contentInset = Telegram.WebApp.contentSafeAreaInset;

// Combine with device safe area
const safeInset = Telegram.WebApp.safeAreaInset;
const totalTop = safeInset.top + contentInset.top;

document.querySelector('.content').style.paddingTop = totalTop + 'px';