Introduction: Customizing Your Boot Experience

The Grand Unified Bootloader (GRUB) is a cornerstone of many Linux systems, providing the critical interface between your BIOS/UEFI firmware and your operating system. While often overlooked, GRUB offers extensive customization capabilities, allowing you to tailor its appearance to match your system’s aesthetic or branding. The heart of this customization lies within the theme.txt file. This guide will take you on a deep dive into mastering GRUB themes, focusing on layout, fonts, and images to create truly bespoke bootloader experiences.

A well-crafted GRUB theme not only enhances the visual appeal but can also improve usability by making menu items clearer or providing essential information at a glance. We’ll explore the various directives within theme.txt, providing practical examples and insights into developing your own unique GRUB themes.

Understanding the GRUB Theme Structure

GRUB themes are typically located in /boot/grub/themes/your_theme_name/. Each theme directory must contain at least a theme.txt file, which acts as the main configuration file, along with any necessary images (PNG, TGA) and fonts (.pf2). If you’re starting from scratch, it’s often easiest to copy an existing theme from /usr/share/grub/themes/ and modify it.

The theme.txt file is a plain text file composed of directives that define various aspects of the theme, from background images to font styles and menu item positions. These directives are organized into sections, often implicitly, by the type of element they control.

Basic theme.txt Structure Example

# Global settings1
desktop-image: "background.png"
theme-hide-unsupported: "true"
title-text: "Boot Menu"

# Font definitions
font: "Ubuntu Mono Regular 12", "Ubuntu Mono Regular 16"
item_font: "Ubuntu Mono Regular 14"
label_font: "Ubuntu Mono Regular 10"

# Terminal box (the area where menu items are displayed)
+ terminal_box {
    left: 20%
    top: 20%
    width: 60%
    height: 60%
    color: #ffffff
    transparency: 0
}

# Boot menu items
+ boot_menu {
    left: 50%-item_width/2
    top: 50%-item_height*item_count/2
    width: 50%
    height: 70%
    item_color: #ffffff
    selected_item_color: #ff0000
    item_spacing: 10
    item_padding: 5
    menu_pixmap_mgr: "menu_hl.png"
}

# Progress bar
+ progress_bar {
    left: 10%
    top: 90%
    width: 80%
    height: 20
    fg_color: #00ff00
    bg_color: #333333
}

# Other labels (e.g., help text)
+ label {
    text: "Press 'e' to edit, 'c' for command line"
    left: 50%-text_width/2
    top: 95%
    color: #aaaaaa
}

Mastering Layout and Positioning

GRUB themes use a coordinate system where (0,0) is the top-left corner of the screen. Positions and sizes can be specified in pixels (e.g., width: 800) or as percentages of the screen dimensions (e.g., left: 20%). This flexibility allows themes to adapt to various screen resolutions.

Key Layout Directives:

• left, top, width, height: Define the bounding box for an element.
• item_spacing: Vertical spacing between menu items.
• item_padding: Padding around individual menu items.
• Relative positioning: You can use expressions like left: 50%-item_width/2 to center elements dynamically based on their calculated width/height.

For elements like boot_menu or terminal_box, defining a precise bounding box is crucial. The terminal_box essentially defines the canvas where GRUB renders its text-based output, including the boot menu. For graphical themes, you’ll typically configure individual elements like boot_menu and progress_bar.

Font Configuration: Elegance in Text

GRUB requires fonts in the `.pf2` format. You can convert TrueType (TTF) or OpenType (OTF) fonts using the grub-mkfont utility. For instance, to convert a font and save it in your theme directory:

grub-mkfont -s 14 -o /boot/grub/themes/mytheme/UbuntuMonoRegular14.pf2 /usr/share/fonts/truetype/ubuntu/UbuntuMono-R.ttf
grub-mkfont -s 16 -o /boot/grub/themes/mytheme/UbuntuMonoRegular16.pf2 /usr/share/fonts/truetype/ubuntu/UbuntuMono-R.ttf

Once converted, you reference them in theme.txt:

font: "UbuntuMonoRegular14.pf2", "UbuntuMonoRegular16.pf2"
item_font: "UbuntuMonoRegular14.pf2"
selected_item_font: "UbuntuMonoBold14.pf2" # Optional, if you want a different font for selected items
label_font: "UbuntuMonoRegular10.pf2"

The font directive typically takes a comma-separated list of fonts. GRUB will attempt to use the first font that loads successfully. You can define specific fonts for different elements:

• item_font: For standard menu entries.
• selected_item_font: For the currently highlighted menu entry.
• label_font: For informational labels.
• menu_font: (Deprecated/less common for newer themes, but good to know)

Colors are specified using hexadecimal RGB values (e.g., #RRGGBB):

item_color: #ffffff     # White
selected_item_color: #ff0000 # Red
label_color: #cccccc   # Light grey

Integrating Images and Graphical Elements

Images add significant visual flair. GRUB supports PNG and TGA formats. For optimal performance and compatibility, it’s recommended to use images that match your screen’s resolution or are slightly larger, allowing GRUB to scale them down. Avoid very large images to prevent slow boot times.

Key Image Directives:

• desktop-image: The background image for the entire GRUB screen.
• selected_item_pixmap: An image that highlights the currently selected menu item. This can be a simple rectangle or a more complex design.
• menu_pixmap_mgr, menu_pixmap_entry: More advanced directives for managing menu item backgrounds, often used with nine-patch scaling for dynamic sizes.
• scrollbar_thumb, scrollbar_track: Images for custom scrollbars if your menu has too many items.

To use a background image:

desktop-image: "background.png"

For a custom selection highlight (assuming selection_highlight.png is in your theme directory):

+ boot_menu {
    # ... other properties ...
    menu_pixmap_mgr: "selection_highlight.png"
    # If using menu_pixmap_mgr, item_pixmap_style might be needed
    # item_pixmap_style: "tile"
}

Transparency is fully supported for PNG images, allowing for sophisticated overlay effects. Ensure your PNGs have an alpha channel for transparency to work correctly.

Configuring Specific GRUB Elements

Beyond global settings, theme.txt allows detailed configuration of specific UI elements using the + element_type { ... } syntax.

+ boot_menu

This is arguably the most important section, controlling the main boot entry list.

+ boot_menu {
    left: 15% # Example: 15% from left edge
    top: 20% # Example: 20% from top edge
    width: 70% # Example: 70% width of the screen
    height: 60% # Example: 60% height of the screen
    item_color: #e0e0e0
    selected_item_color: #ffffff
    item_background_color: #00000000 # Transparent background for items
    selected_item_background_color: #2a3a4a # A subtle dark blue for selected item background
    item_spacing: 15 # More space between items
    item_font: "myfont_16.pf2"
    selected_item_font: "myfont_bold_16.pf2"
    menu_pixmap_mgr: "selector_box.png" # Use a custom image for the selector
}

Note the 8-digit hex color for item_background_color. The last two digits (00) represent the alpha channel, making it fully transparent.

+ progress_bar

Indicates the boot countdown or loading progress.

+ progress_bar {
    left: 20%
    top: 85%
    width: 60%
    height: 10
    fg_color: #00ff00 # Green foreground
    bg_color: #333333 # Dark grey background
    border_color: #00aa00 # Darker green border
    border_style: "line"
}

+ label

For displaying arbitrary text, like instructions or a clock.

+ label {
    text: "Time: %H:%M:%S"
    left: 80%
    top: 5%
    color: #ffffff
    font: "UbuntuMonoRegular12.pf2"
}

+ label {
    text: "Use arrow keys to navigate"
    left: 50%-text_width/2 # Center horizontally
    top: 90%
    color: #aaaaaa
    font: "UbuntuMonoRegular10.pf2"
}

Labels support special variables like %H:%M:%S for time.

Applying and Testing Your Theme

Once you’ve crafted your theme.txt and gathered your assets, you need to enable it.

1. Place your theme folder (e.g., mytheme/) in /boot/grub/themes/.
2. Edit /etc/default/grub and add or modify the GRUB_THEME line:

   GRUB_THEME="/boot/grub/themes/mytheme/theme.txt"

3. Update GRUB’s configuration:

   sudo grub-mkconfig -o /boot/grub/grub.cfg

4. Reboot your system to see your custom theme in action.

Troubleshooting Tips:

• Check GRUB’s log if it fails to load the theme. Sometimes, error messages appear directly on the screen.
• Ensure all image and font paths in theme.txt are correct and relative to the theme directory.
• Verify image formats (PNG or TGA only).
• Ensure fonts are properly converted to `.pf2` format.
• Start simple. Get a background image and basic menu working, then add complexity.

Conclusion

Mastering theme.txt opens up a world of possibilities for customizing your GRUB bootloader. By understanding the directives for layout, fonts, and images, you can move beyond default themes and create a truly personalized and professional boot experience. Experiment with different configurations, colors, and graphics to make your boot screen reflect your system’s unique identity. The power to design your bootloader is now in your hands!