The rEFInd Boot Manager:
Theming rEFInd

by Roderick W. Smith, rodsmith@rodsbooks.com

Originally written: 4/19/2012; last Web page update: 5/5/2013, referencing rEFInd 0.6.10

I'm a technical writer and consultant specializing in Linux technologies. 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!

Donate $1.00	Donate $2.50	Donate $5.00	Donate $10.00	Donate $20.00	Donate another value

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.

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.
• Icons—rEFInd uses icons for its OSes and utilities. 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.
• 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.
• fonts—rEFInd uses a 14-point monospaced 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 PNG image of the font's characters, which limits rEFInd's font capabilities.

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.

You can create a new background image and logo by placing a PNG or BMP 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:

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 text color is determined by the brightness of the background; rEFInd uses black text against light backgrounds and light 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 image from the banners subdirectory of the rEFInd package in your background.

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 a few ways:

• 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 PNG for ICNS files, with a suitable filename change), and are fairly self-explanatory. OS tags should be 128x128 pixels, while tags for 2nd-row utilities should be 48x48 pixels. 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 either Apple's icon image (ICNS) or Portable Network Graphics (PNG) format. PNG files are easier 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 install.sh script to upgrade rEFInd will replace your customized icons.
• You can customize the appearance of an individual boot loader by placing an ICNS or PNG file in its directory with the same name as the boot loader but with a .icns or .png extension. For instance, if your boot loader program is elilo.efi, you can create a custom icon by naming it elilo.png.
• You can provide an icon for boot loaders stored in the root directory of a filesystem by placing a file called .VolumeIcon.icns or .VolumeIcon.png in that volume's root.
• You can set a custom badge (the 48x48-pixel icon that identifies the disk type) by creating a file called .VolumeBadge.icns or .VolumeBadge.png in that volume's root. This setting applies to all the boot loaders found on this volume, even if they're in subdirectories.

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 in PNG or in Microsoft's BMP format. 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 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 BMP doesn't support transparency (alpha channels), you must use the PNG format 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 a PNG 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. 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.

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 be in PNG format (the BMP format doesn't support an alpha layer, which is required for proper transparency). They 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. In practice, this is likely to be tedious.

I used icons from the Oxygen Icons project, both from the Oxygen Refit package and from Gentoo's oxygen-icons package. These icons supplemented or replaced icons that rEFIt used; however, many OS icons (such as those for Windows and Mac OS) are carried over from rEFIt. I've also used a handful of icons for individual Linux distributions from other sources—usually documentation associated with the distribution in question.

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

• ecto-plazm's theme
• The Gris Theme (also available as an Arch Linux package.)

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–2013 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.