Complete guide to Android Telegram theming

SnejUgal

Telegram for Android lets you create and use themes. This article is the complete guide to them—how to install, create them and so on.

Installing themes

Since Telegram started supporting themes, a lot of channels and groups for themes appeared, e.g. @androidthemes, @themesandroid, @by_snejugal, @androidthemesgroup, etc. You'll find a lot of themes in these channels and groups.

When you find a theme for yourself, just tap the theme file (all Android Telegram themes' extension is .attheme).

When the file downloads, tap it again.

When you tap, a preview of the theme shows up—you can see what the theme looks like on your device. There are two screens—chat screen and chats list screen—are available for preview. You can see both them by swiping left and right.

If you want to apply the theme, tap the Apply button, if not, tap either the Cancel button or the system back button (not that one in chat preview!)

When you apply a theme, Telegram changes its colors.

You can apply as many themes as you want.

I've downloaded a theme from some website and it doesn't apply

Yes, applying a theme outside Telegram won't work:

You can only apply a theme inside Telegram but not outside. So you have to share the theme via Telegram:

with yourself using Saved Messages:

Now you can apply the theme as it's inside Telegram:

List of themes

Telegram remembers all themes you've ever applied. This list is available in Settings → Theme.

It shows the current theme and other themes you've ever applied. There are three dots icon beside each theme, tapping which opens this menu:

The Share button opens the list of apps via which you can share the theme;
The Edit button begins editing the theme;
The Delete button removes the theme out of the list.

For built-in themes, only the Share button is displayed.

Tapping a theme applies it. Holding a theme shows the menu above.

Creating a theme

When themes just got released, there was only the in-app editor. Nowadays, there are also third-party editors made by the community.

In-app editor

The in-app editor is a good choice for a beginner. You can see the changes you make instantly (but not always—there's another article on this), and the variables list depends on the screen you are on.

To create a new theme, tap the Create new theme button on the themes list. It will suggest you to name your theme:

When you enter the name and tap OK, a new theme is created and applied, and your new theme is based on the theme you had applied before tapping the Create button. You'll also see a palette icon. You can move this icon anywhere on your screen; if you move it to the screen edge, the theme is saved and the icon disappears.

When you tap the icon, you'll see a list like this one:

The Close editor button hides this list but leaves the palette icon on the screen;
The Save theme button closes the list and takes the palette icon away. You can always return the icon back by tapping the Edit button on a theme's menu.

The words such as windowBackgroundWhite, actionBarDefault etc. are called variables. The colors applied to variables are called values, they are shows on the left to the variables.

When you tap a variable, this screen shows up:

Let's describe it in details.

The first three text fields are for RGB channels. The first one is the red channel, the second one is the green one and the third one is the blue one. The greater a value is, the more the final color has it. The value can be between zero and 255. You can learn more about RGB on Wikipedia;
The fourth text field is opacity. The value is between zero and 255 as well; the greater the value, the more opaque the color is;
The color wheel sets the hue and saturation of the color in the HSV color model;
The brightness slider sets the brightness level in the HSV color model;
The opacity level sets the opacity level of the color;
The Cancel button denies the color changes. It will cancel them even if you apply them and you open the same variable and tap this button at once;
The Default button resets the value to default;
The Save button saves the value.

Try changing the fields, wheel and sliders and you'll understand what they do.

You can try opening the editor on another screen and you'll see another list of variables:

Usually the list contains the variables you may face on the current screen. But these lists are not created automatically but by hand by the developer, so it is not rare not to find some variable inside the app.

This editor doesn't support HEX, searching through variables and may even distort the colors. Due to these issues, the community creates their editors with no bugs but improvements.

Third-party editors

To use community editors, you should first learn how to export and import themes. The import process is described above; the export process is:

1. If the theme isn't shared in any chat, follow steps 2-5, otherwise go to step 6.

2. Open the theme list, find the theme you want to share and tap the three dots beside it.

3. Tap Share.

4. Select Telegram.

5. Tap the Saved Messages chat at the top of the list.

6. Download the theme if it isn't downloaded.

7. When the theme is downloaded, tap the three dots at the top right corner of the bubble.

8. Tap Save to Downloads.

You might notice that you can select any app in step 4. It doesn't matter unless you can't extract the file from the app via which you shared your file.

Once you do the steps, the theme is saved in your Downloads folder. You can open this theme in any editor you'll like.

At this time, there are two editors made by @snejugal and by @YouTwitFace. We're going to look at both of them.

.attheme editor by @snejugal

When you open the editor, it will suggest you to create a new theme or open an existing file.

Let's open an existing one. Tap Open an existing file and select Documents (this menu may depend on your browser and device).

And select the theme you want to open.

After you do it, you'll see a screen like this one:

The field at the top with words Amber Darkened is the theme name field, it lets you easily rename your theme (using in-app editor, you have to create a new theme);
The Close theme button closes the theme letting you open another theme;
The Download for further editing button editing button downloads an .attheme-editor file for further editing in this editor, keeping the same name, theme and palette;
The Compare with another theme button opens a tool to compare two themes preloading the opened theme in this editor;
The Find or add a variable… field lets you find variables and add them (there's no search in the in-app editor);
The download button in the bottom right corner downloads the .attheme file, optimizing it if possible.

The list of variables goes next. It looks like this:

A variable “card” has a name of the variable, its value written as HEX and RGBA and the preview of the color in the background. You'll see if a variable is transparent what you can't do using the in-app editor.

When you tap a variable “card”, you'll see this dialog:

It has two tabs. The first Value tab lets you set the color itself using either HEX, RGB or HSL and its alpha. The second Palette tab lets you select a color that's already added in your theme.

It is worth noticing that the alpha isn't changed when you select a color on the palette, which is pretty convenient. Tapping a color twice removes it from the palette. The first color on the palette is the default value of the variable, it doesn't show up only when editing chat_wallpaper.

Palette is a powerful feature of the editor, simple at first glance. You can only specify a color once and then take it on the palette and not typing its value again and again. What's more, you won't get a lot of color variations made by typos when typing the values that mean nothing for a man's brain.

The editor gradually gets previews of variables—what it will look like inside the Telegram app. The preview is completely colored in colors of the theme.

The pro of this feature is that you can see what elements it's hard to get which look like. However, the editor has just few of them what's going to become opposite through time.

Let's look at the search bar. When you tap it, a full list of variables in alphabetical order is shown that you can scroll:

When typing letters, only variables that fit the query are shown:

Tapping a variable starts its editing. The variables is automatically added in the theme if not.

Unfortunately, only one theme can be opened at the same time. It's impossible to set an image as the chat background, it is only saved on theme upload and kept in the file when download. But the pros are: offline mode, compatibility with both PC and Android and Drag-and-drop support:

lungers.com/attheme by @youtwitface

Probably, this editor isn't so handy than the one above is. However, it has a few features that one doesn't. When you open it, you'll see only one button telling you to open a theme.

This screen appears after you open a theme:

The button at the top with current theme's name opens another theme;
The link below Edit theme heading opens the glossary of variables;
The Variable(s) field is filled with a list of variables separated by comma. Predictions are shown as you type;
The HEX field is filled with the value you want to turn entered variables to. As you activate this field, you'll see a panel with RGB channels and alpha fields to easily convert RGB to HEX and put it in the HEX field.

The Invert button inverts all color of the opened theme;
The Download button downloads the theme.

Hopefully the author of this editor improves it soon. But now, let's look at CLIs.

General information on CLIs

CLI stands for Command-line interface. If you don't have a computer, you'll have a hard time using them.

The CLIs we're going to look at are written in JS and running on Node.js. If you don't have Node.js and npm installed, check out the official website to learn how to do that.

If you're interesting in using CLIs but don't know how to, I recommend you to read guides on this topic.

attheme-cli

To install attheme-cli, run npm i -g attheme-cli:

snejugal@snejugal:~$ npm i -g attheme-cli
npm WARN deprecated attheme-default-values@1.2.2: Default values are now a part of attheme-js
/home/snejugal/.nvm/versions/node/v12.11.1/bin/attheme -> /home/snejugal/.nvm/versions/node/v12.11.1/lib/node_modules/attheme-cli/index.js
+ attheme-cli@1.0.0
added 41 packages from 23 contributors in 5.4s

When it's installed, you can run the attheme command in a directory which contains themes (you can also run npx attheme-cli, which temporarily installs the package):

snejugal@snejugal:~$ attheme
? Which theme do you want to open? (Use arrow keys)
❯ Create an empty theme 
  Open the default theme 
  bluebubbles 
  onemorelight

The CLI will suggest you either to create a new theme, open the default theme or open one of themes in the working directory. By hitting top/bottom arrows, the selected item changes. After you choose a theme, you can run commands.

snejugal@snejugal:~$ attheme
? Which theme do you want to open? bluebubbles
? Command: (Use arrow keys or type to search, tab to autocomplete)
❯ help 
  valueof 
(Move up and down to reveal more choices)

You can see the list of available commands using the help command.

? Command: help
 help
  shows the list of commands.
 valueof <variable> [<variable> [...]]
 get <variable> [<variable> [...]]
  both commands show the value of the variables.
 set <variable> [<variable> [...]] <value>
  sets the value of the variables to <value>. <value> may be either #rgb, #argb, #rrggbb, #aarrggbb or r g b [a] (ints from 0 to 255)
 delete <variable> [<variable> [...]]
  deletes the variables in the theme.
 exportwallpaper <file>
  exports the wallpaper of the theme to <file>.
 importwallpaper <file>
  imports the image from <file> into the theme.
 save [<file>]
  saves the theme. If <file> is specified, then the theme will be saved into it.
 exit
  closes the CLI without saving the theme. 
More complete description of commands is on npmjs.com/package/attheme-js.

It is pretty hard to create a theme using a CLI, but it is ideal to fix a bug in a theme or add a new variable.

Text editors

Any theme can be edited with a text editor. But it's not convenient and the image of your theme can be damaged; however, we can look at the structure of .attheme files.

Let's open a theme. You'll see something like this:

avatar_backgroundViolet=-14865606
dialogRadioBackground=-16746832
profile_adminIcon=-8483172
chat_replyPanelClose=-14966030
avatar_backgroundBlue=-14865606
…

One can already see the structure:

variable=value
variable=value
…

But what do these numbers mean? Let's look into it.

Let's take any HEX color, for example, #1ba1f3. Omit # and bring the alpha value back to the beginning of the hex, so that we get ff1ba1f3. Let's look at this number in binary:

snejugal@snejugal:~$ node
Welcome to Node.js v12.11.1.
Type ".help" for more information.
> 0xff1ba1f3.toString(2)
'11111111000110111010000111110011'

and measure the length of this string:

> _.length
32

Let's look at this number as a 32-bit signed integer. The first bit is 1, so the number is negative. Now we have to get the absolute value of this number, so we subtract that part by 1 and invert the bits:

> ~(0b11111111000110111010000111110011 - 1)
14966285

And now let's find -14966285 in the file:

snejugal@snejugal:~$ grep -14966285 bluebubbles.attheme
chat_inLoader=-14966285

If you do it vice versa, you can turn a signed integer to a HEX value. But it can be easier:

> (-14966285 >>> 0).toString(16) // int to hex
'ff1ba1f3'
> 0xff1ba1f3 >> 0 // hex to int
-14966285

Probably, you will set values more often than look at them in the text editor. Fortunately, you can specify a HEX value—either #rrggbb or #aarrggbb:

chat_inLoader=#1ba1f3

You can leave comments in the file, but only on new lines:

// do:
// nice comment
chat_inLoader=#1ba1f3

// don't:
windowBackgroundGray=-14404537 // nice color

Let's go deeper:

You can see that some binary code begins here—it is the image wallpaper of the theme. The beginning of the image is marked with WPS—Wallpaper start—on the line before the image starts. The end of the image is optionally marked with WPE—Wallpaper end—on the line after it.

Now you know the structure of .attheme files and, if you're a developer, you can build tools for themes. But if you're a JS developer, you can use attheme-js instead of inventing the wheel, or, if you're a Rust developer, you can use attheme-rs.

Most probably your editor will distort the image correctly when saving the theme—for this reason, you should avoid using text editors and instead use the in-app editor, third-party editors or, at least, HEX editors.

We didn't describe each variable here—there's a glossary of them all. Use it when you don't know what a variables changes, but still try to find it on your own. You may also use @atthemeglossarybot for quicker access to the glossary, but it still knows less than the glossary does. Anyway, people in theme groups can help you with variables!