The rEFInd Boot Manager:
Theming rEFInd

by Roderick W. Smith, rodsmith@rodsbooks.com

Originally written: April 19, 2012; last Web page update: 3/24/2024, referencing rEFInd 0.14.1

This Web page is provided free of charge and with no annoying outside ads; however, I did take time to prepare it, and Web hosting does cost money. If you find this Web page useful, please consider making a small donation to help keep this site up and running. Thanks!

This page is part of the documentation for the rEFInd boot manager. If a Web search has brought you here, you may want to start at the main page.

rEFInd relies on both built-in and external graphical elements in its user interface, and all of these elements can be replaced by user-specified files. This fact makes rEFInd's "look and feel" highly adjustable even by non-programmers. This page will help you get started in making such changes to each of the major sets of features: banners and backgrounds, icons, icon selection backgrounds, and fonts. I conclude this page with pointers to a few themes that users have created for rEFInd.

Broadly speaking, rEFInd's graphical elements fall into four categories:

• Banners and backgrounds—A banner is a logo or small graphical element that rEFInd displays horizontally centered in the top half of the screen. The rest of the screen is filled with a solid color derived from the color used in the top-left pixel of the banner image. rEFInd includes a built-in banner image that's used if you don't specify another image with the banner token in refind.conf. A background is simply a banner image that fills the screen. As a general rule, PNG and JPEG files work best for this element.
• Icons—rEFInd uses icons for its OS and utility selection tags. The vast majority of these icons are loaded from disk files and so are easily replaced without adjusting the refind.conf file. Alternatively, you can specify a new icons directory with the icons_dir token in refind.conf. Icons are generally PNG or ICNS files, with the latter being a Mac-centric format and so less common.
• Icon selection backgrounds—When an icon is selected, it's merged with a slightly larger selection icon, which you can change by specifying a new file with the selection_big and selection_small tokens in refind.conf. These elements are generally best done as PNG files.
• fonts—rEFInd uses a 14-point monospaced sans serif font by default. If you don't like this font, you can change it to another monospaced font by using the font token in refind.conf; however, the font file is a simple image of the font's characters, which limits rEFInd's font capabilities. The PNG format works best for a font.

Of course, not all of these elements are likely to be included in all themes. You might want to change just one or two elements—say, to add an icon for your OS or to change the banner or background.

As noted in the Setting OS Icons section of the Configuring the Boot Manager page, rEFInd supports four image file formats: Apple's ICNS format, Portable Network Graphics (PNG) format, bitmap image file (BMP) format, and Joint Photographic Experts Group (JPEG) format. The demands of each type of image mean that certain file formats work best for it, as noted above; however, you can in principle use any file format for any purpose. Specific file format limitations include:

• rEFInd's BMP and JPEG implementations lack support for transparency, which is highly desirable in icons, icon backgrounds, and fonts.
• Apple's ICNS format supports a limited range of sizes, all of which are square, not rectangular. On the other hand, ICNS supports multiple resolutions in one file, which can be desirable for icons.
• rEFInd's BMP implementation does not support compression, so full-screen BMP images will be quite large.

rEFInd relies on the LodePNG and NanoJPEG libraries for PNG and JPEG support, respectively. These libraries have certain limitations; for instance, NanoJPEG, and therefore rEFInd, does not support progressive JPEGs. If you have problems with a specific icon or banner image, check the libraries' pages and re-save or convert the image into a more generic form, or even to a different format.

The rest of this document describes adjusting rEFInd's themes manually. I haven't tried it myself, but the refind-theme-editor project on GitHub claims to help automate this process.

You can create a new background image and logo by placing an image file in rEFInd's main directory and passing its filename to rEFInd with the banner option in refind.conf. If the image is smaller than the screen, the color in the top-left pixel of the image will be used for the rest of the display. This pixel's color is also used as the background color for submenu text, even for full-screen backgrounds. Using a full-screen background image can produce a dramatically different "look" for rEFInd:

Tip: If you use a laptop, you can create a banner or background that includes your contact information. If you lose your laptop and it's found by an honest person, this should facilitate your getting it back. Setting timeout 0 in refind.conf will ensure that the message remains on the screen indefinitely unless a loader is launched.

Note that in this example, the text immediately below the icons is white, whereas the hint text at the bottom of the screen is black. (The "Rod Smith's Laptop" and other text at the top is part of the image.) The text color is determined by the brightness of the background; rEFInd uses black text against light backgrounds and white text against dark backgrounds. This adjustment is done on a line-by-line basis, so it copes better with horizontal lines than with vertical lines.

If you want to use a full-screen background but also include the rEFInd logo, you can merge the two in a graphics editor by including the refind_banner-alpha.png or refind-banner.svg image from the banners subdirectory of the rEFInd package in your background.

It's possible to stretch or shrink any image to fill the screen. To do so, you should use the banner_scale option in refind.conf: Set it to noscale (the default) to use small banners as such or to crop larger images; or set it to fillscreen to adjust your banner's size to exactly fill the screen. This should be particularly handy for theme developers who want to use a full-screen background image, since you can do this with just one image file.

Prior to version 0.10.0, rEFInd's icons came from a variety of sources—mostly from the Oxygen Refit package, with OS icons from rEFIt and assorted other sources. If you prefer these icons to the new ones, you can pull them out of a rEFInd 0.9.2 (or earlier) package

The core icons in rEFInd 0.10.0 and later come from the AwOken 2.5 icon set, with additional icons created by me, and a few others taken from other sources. (The details are documented in the README file in the icons subdirectory.) These icons have a "flat" appearance, but with drop shadows to provide a type of depth. Most of the individual icons use just one color, aside from the drop shadow. Of course, the point of themes is that you might get bored with, or simply not like, the default graphics, so you can change them.

As described on various other pages of this document, rEFInd relies on icon files located in its icons subdirectory, and occasionally elsewhere, to define its overall appearance. You can adjust rEFInd's icons in several ways, as detailed in the Setting OS Icons section of Configuring the Boot Manager. For creating a theme, though, the following techniques are most helpful:

• You can create new icons, place them in a subdirectory of rEFInd's main directory, and tell the program to use the new icons by setting the icons_dir token in refind.conf. This will affect the appearance of the OS tags, the utility tags, and so on. The names of these icons should match those in the icons subdirectory (although you can substitute file formats, with a suitable filename change), and are fairly self-explanatory. The default size for OS tags is 128x128 pixels, tags for 2nd-row utilities are ordinarily 48x48 pixels, and drive-type badges are 32x32 pixels by default. If an icon is missing from the directory specified by icons_dir, rEFInd falls back to the icon from the standard icons subdirectory; thus, you can replace just a subset of the standard icons. rEFInd can use icons in any of several formats, as described earlier, in Theming Basics. PNG files are the easiest to generate on most platforms. You can generate ICNS files in various Apple programs or by using the libicns library (and in particular its png2icns program) in Linux.
• You can do as above, but place your new icons in the default icons subdirectory. This method is discouraged because using the refind-install script to upgrade rEFInd will replace your customized icons.
• You can adjust the sizes of icons by using the big_icon_size and small_icon_size tokens in refind.conf. These tokens adjust the size of the first-row OS and second-row tool icons, respectively. The big_icon_size option also indirectly sets the disk-type badge size; badges have sides that are 1/4 the size of OS icons. The icons provided with rEFInd are 128x128 for OS icons, 48x48 for tools, and 32x32 for badges. The big_icon_size and small_icon_size tokens cause these icons to be scaled to the desired value; however, for best results you should replace the default icons with ones generated natively in the desired size. (All the image file formats supported by rEFInd are bitmap formats, and so the images will be degraded by scaling operations.)

As an example of what the combination of icons and backgrounds can do, consider my own Snowy theme, showing the same boot options as the preceding image:

rEFInd identifies the current selection by displaying a partially-transparent icon "between" the OS or tool icon and the background image. The default icon works reasonably well on both solid and image backgrounds, but if you like, you can customize it by creating new icons. You should create both 144x144 and 64x64 images and tell rEFInd about them by using the selection_big and selection_small tokens, respectively, in refind.conf. (If you scale your icons, you may want to adjust the selection tile images appropriately. The big image is 9/8 the size of its matching icons, while the small tile is 4/3 the size of its icons.) If you omit the large icon, rEFInd will stretch the small icon to fit the larger space; if you omit the small icon, rEFInd will use the default small icon. Because PNG supports both transparency and the unusual sizes of the selection icon, PNG is best if you want your selection background to show the underlying image beneath it. (You can create the illusion of transparency on a solid background by matching the colors, though.)

rEFInd's default font is a 14-point (12-point in 0.6.5 and earlier) serif monospaced font. I also include a handful of alternatives in the fonts subdirectory. rEFInd's font support is extremely rudimentary, though; it reads an image file that holds the glyphs from ASCII 32 (space) through ASCII 126 (tilde, ~), plus a glyph that's displayed for all characters outside of this range. Thus, rEFInd can't currently display non-ASCII characters or use proportional (variable-width) fonts. You can change the font from one monospaced font to another and change the font size, though.

If you want to create your own fonts, you can do so. If you're using Linux, the mkfont.sh script in the fonts subdirectory will convert an installed monospace font into a suitable format. (This script works properly for most fonts, but if a font is unusually thin or wide, you will have to adjust the let CellWidth= line near the end of the file.) You can use it like this:

$ ./mkfont.sh Liberation-Mono-Italic 14 -1 liberation-mono-italic-14.png

The result is a PNG file, liberation-mono-italic-14.png, that you can copy to your rEFInd directory and load with the font token in refind.conf, as in:

font liberation-mono-italic-14.png

The mkfont.sh script takes four arguments:

• The font name—Type convert -list font | less to obtain a list of fonts available on your computer. Note, however, that rEFInd requires monospaced (fixed-width) fonts, and most of the fonts installed on most computers are variable-width.
• The font size in points
• A y offset—Many fonts require an adjustment up (negative values), or occasionally down (positive values) to fit in the PNG image area. You'll have to use trial and error to get this to work.
• The output filename

I recommend checking the PNG file in a graphics program like eog before using it. Note that the font files should have an alpha layer, which many graphics programs display as a gray-and-white checkered background. This requirement, combined with ICNS's limited set of supported sizes, makes PNG the only practical file format for rEFInd fonts.

If you're not using Linux, or if you want to use some other method of generating fonts, you can do so. The font files must contain glyphs for the 95 characters between ASCII 32 (space) and ASCII 126 (tilde, ~), inclusive, plus a 96th glyph that rEFInd displays for out-of-range characters. To work properly, the characters must be evenly spaced and the PNG image must be a multiple of 96 pixels wide, with divisions at appropriate points. In theory, you should be able to take a screen shot of a program displaying the relevant characters and then crop it to suit your needs and convert the background color to transparency. In practice, this is likely to be tedious.

In addition to this default icon set, I've received word of a few other rEFInd themes:

• Snowy is my own theme. It's built from (mostly) white variants of rEFInd's standard icons and includes a photo of a snowy field as a background image. It's shown earlier on this page.
• ecto-plazm's theme was one of the first independent themes to be created for rEFInd.
• Evan Purkhiser's Minimal theme uses black icons on a gray background of varied brightness, as shown here:



• John Trenton Cary's rEFInd Metro theme is another minimal theme. It uses a solid background color and a number of OS icons.



• Sean Gibbons' rEFInd Next theme is "inspired by both iOS 7 and Windows 8 interfaces." It includes both a background image and a number of OS icons.



• Zhu Qunying has created a Slackware-themed banner logo for rEFInd. Although it's not a full theme, I thought I'd mention it.
• naymlezwun has created an OS X theme for rEFInd.



• jamaladdeen on deviantART has created another OS X theme that resembles the macOS environment.



• Brian Lechthaler has created an alternative rEFInd banner:
  
  
• User munlik has created a theme called Regular-theme on Deviantart. The original developer of this theme seems to have abandoned it, but bobafetthotmail provides a variant with additional icons hosted on github.



• Despite its name, the Tux Boot Loader Theme for Ubuntu can be used with any Linux distribution (or on a system without Linux installed at all).



• The rEFInd Ambience Theme is another one with minimalistic icons against a shaded background.



• The rEFInd-Chalkboard theme by AliciaTransmuted emulates the appearance of writing on a chalkboard. See here for all of AliciaTransmuted's rEFInd themes.



• The rEFInd-Details theme by AliciaTransmuted implements many unique and colorful icons. See here for all of AliciaTransmuted's rEFInd themes.



• The rEFInd-Indulgence theme by AliciaTransmuted uses a background that resembles soft leather. See here for all of AliciaTransmuted's rEFInd themes.



• The rEFInd-Wildside theme by AliciaTransmuted uses a dark background and dark red icons. See here for all of AliciaTransmuted's rEFInd themes.



• The rEFInd-splash theme by AliciaTransmuted provides a swimming pool theme to the rEFInd main screen. See here for all of AliciaTransmuted's rEFInd themes.



• HI-THEMES by SLywnow is set of colorful themes with a tool for managing them. Most of the themes are dominated by a single color, like the red one shown here:



• Papirus by Duke93 uses distinctive icons against a dark background.

If you've created or discovered another rEFInd theme, please tell me about it so that I can provide a link to it from this page.

copyright © 2012–2023 by Roderick W. Smith

This document is licensed under the terms of the GNU Free Documentation License (FDL), version 1.3.

If you have problems with or comments about this Web page, please e-mail me at rodsmith@rodsbooks.com. Thanks.

Go to the main rEFInd page

Learn about methods of booting Linux with rEFInd

Return to my main Web page.