1ROFI-THEME(5) File Formats Manual ROFI-THEME(5)
2
6 rofi-theme - Rofi theme format files
7
10 The easiest way to get started theming rofi is by modifying your exist‐
11 ing theme.
12 Themes can be modified/tweaked by adding theming elements to the end of
15 the
16 config file. The default location of this file is ~/.config/rofi/con‐
17 fig.rasi, if the file does not exists, you can create it.
18 A basic config:
21 configuration {
24 modes: [ combi ];
25 combi-modes: [ window, drun, run ];
26 }
27 @theme "gruvbox-light"
29 /* Insert theme modifications after this */
31 For example if we want to change the Type to filter text in the entry
35 box we append the following:
36 entry {
39 placeholder: "Type here";
40 }
41 In the above section, entry indicates the widget, placeholder is the
45 property we want to modify and we set it to the string "Type here". To
46 find the commonly available widgets in rofi, see the 'Basic structure'
47 section.
48 To change the mouse over cursor to a pointer, add:
51 entry {
54 placeholder: "Type here";
55 cursor: pointer;
56 }
57 For the next modification, we want to add the icon after each text ele‐
61 ment and increase the size. First we start by modifying the element
62 widget:
63 element {
66 orientation: horizontal;
67 children: [ element-text, element-icon ];
68 spacing: 5px;
69 }
70 Resulting in the following packing:
75 ┌─────────────────────────────────────────────────────────────────────┐
78 │ element │
79 │ ┌─────────────────────────────────────────────┐ ┌─────────────────┐ │
80 │ │element─text │ │ element─icon │ │
81 │ └─────────────────────────────────────────────┘ └─────────────────┘ │
82 └─────────────────────────────────────────────────────────────────────┘
83 The element (container) widget hold each entry in the listview, we add
87 the two pre-defined children in the order we want to show. We also
88 specify the packing direction (orientation) and the spacing between the
89 children (spacing). We specify the space between the two children in
90 absolute pixels (px).
91 To increase the icon-size, we need to modify the element-icon widget.
94 element-icon {
97 size: 2.5em;
98 }
99 ┌─────────────────────────────────────────────────────────────────────┐
103 │ element │
104 │ ┌─────────────────────────────────────────────┐ ┌─────────────────┐ │
105 │ │element─text │ │ element │ │
106 │ │ │ │ ─ │ │
107 │ │ │ │ icon │ │
108 │ └─────────────────────────────────────────────┘ └─────────────────┘ │
109 └─────────────────────────────────────────────────────────────────────┘
110 In this example we specify the size in the em
114 ⟨https://www.w3.org/Style/LieBos3e/em⟩ unit.
115 Now lets change the text color of both the entry and the element-text
118 widget to red and background to blue.
119 entry, element-text {
122 text-color: red;
123 background-color: rgb(0,0,255);
124 }
125 Here we use two different methods of writing down the color, for text-
129 color we used a named color, for background-color we specify it in rgb.
130 We also specify the property for multiple widgets by passing a comma
131 separated list of widget names.
132 If you want to center the text relative to the icon, we can set this:
135 element-text {
138 vertical-align: 0.5;
139 }
140 ┌─────────────────────────────────────────────────────────────────────┐
144 │ element │
145 │ ┌─────────────────────────────────────────────┐ ┌─────────────────┐ │
146 │ │ │ │ element │ │
147 │ │element-text │ │ ─ │ │
148 │ │ │ │ icon │ │
149 │ └─────────────────────────────────────────────┘ └─────────────────┘ │
150 └─────────────────────────────────────────────────────────────────────┘
151 If you want to see the complete theme, including the modification you
155 can run:
156 rofi -dump-theme
159
163 By default, rofi loads the default theme. This theme is always loaded.
164 The default configuration contains:
165 @theme "default"
168 To unload the default theme, and load another theme, add the @theme
172 statement to your config.rasi file.
173 If you have a theme loaded via @theme or use the default theme, you can
176 tweak it by adding overriding elements at the end of your config.rasi
177 file.
178 For the difference between @import and @theme see the Multiple file
181 handling section in this manpage.
182 To see the default theme, run the following command:
185 rofi -no-config -dump-theme
188
192 The need for a new theme format was motivated by the fact that the way
193 rofi handled widgets has changed. From a very static drawing of lines
194 and text to a nice structured form of packing widgets. This change made
195 it possible to provide a more flexible theme framework. The old theme
196 format and config file are not flexible enough to expose these options
197 in a user-friendly way. Therefore, a new file format has been created,
198 replacing the old one.
199
203 The encoding of the file is UTF-8. Both unix (\n) and windows (\r\n)
204 newlines format are supported. But unix is preferred.
205
208 C and C++ file comments are supported.
209 • Anything after // and before a newline is considered a com‐
212 ment.
213 • Everything between /* and */ is a comment, this comment can
215 span multiple lines.
216 Comments can be nested and the C comments can be inline.
220 The following is valid:
223 // Magic comment.
226 property: /* comment */ value;
227 However, this is not:
231 prop/*comment*/erty: value;
234
238 White space and newlines, like comments, are ignored by the parser.
239 This:
242 property: name;
245 Is identical to:
249 property :
252 name
253 ;
255
259 The preferred file extension for the new theme format is rasi. This is
260 an abbreviation for rofi advanced style information.
261
264 Each element has a section with defined properties. Global properties
265 can be defined in section * { }. Sub-section names begin with an op‐
266 tional hash symbol #.
267 It is advised to define the global properties section on top of the
270 file to make inheritance of properties clearer.
271 /* Global properties section */
274 * {
275 // list of properties
276 }
277 /* Element theme section. */
279 {element path} {
280 // list of properties
281 }
282 {elements... } {
283 // list of properties
284 }
285 If there are multiple sections with the same name, they are merged. Du‐
289 plicate properties are overwritten and the last parsed entry kept.
290
293 A theme can have one or more global properties sections. If there is
294 more than one, they will be merged.
295 The global properties section denotes the defaults for each element.
298 Each property of this section can be referenced with @{identifier} (See
299 Properties section)
300 A global properties section is indicated with a * as element path.
303
306 A theme can have multiple element theme sections.
307 The element path can consist of multiple names separated by whitespace
310 or dots. Each element may contain any number of letters, numbers and
311 -'s. The first element in the element path can optionally start with a
312 # (for historic reasons). Multiple elements can be specified by a ,.
313 This is a valid element name:
316 element normal.normal {
319 background-color: blue;
320 }
321 button {
322 background-color: blue;
323 }
324 And is identical to:
328 element normal normal, button {
331 background-color: blue;
332 }
333 Each section inherits the global properties. Properties can be explic‐
337 itly inherited from their parent with the inherit keyword. In the fol‐
338 lowing example:
339 window {
342 a: 1;
343 b: 2;
344 children: [ mainbox ];
345 }
346 mainbox {
347 a: inherit;
348 b: 4;
349 c: 8;
350 }
351 The element mainbox will have the following set of properties (if main‐
355 box is a child of window):
356 a: 1;
359 b: 4;
360 c: 8;
361 If multiple sections are defined with the same name, they are merged by
365 the parser. If multiple properties with the same name are defined in
366 one section, the last encountered property is used.
367
370 The properties in a section consist of:
371 {identifier}: {value};
374 Both fields are mandatory for a property.
378 The identifier names the specified property. Identifiers can consist of
381 any combination of numbers, letters and '-'. It must not contain any
382 whitespace. The structure of the value defines the type of the prop‐
383 erty. The current parser does not define or enforce a certain type of a
384 particular identifier. When used, values with the wrong type that can‐
385 not be converted are ignored.
386 The current theme format supports different types:
389 • a string
392 • an integer number
394 • a fractional number
396 • a boolean value
398 • a color
400 • image
402 • text style
404 • line style
406 • a distance
408 • a padding
410 • a border
412 • a position
414 • a reference
416 • an orientation
418 • a cursor
420 • a list of keywords
422 • an array of values
424 • an environment variable
426 • Inherit
428 Some of these types are a combination of other types.
432
435 • Format: "[:print:]+"
436 A string is always surrounded by double quotes ("). Between the quotes
440 there can be any printable character.
441 For example:
444 font: "Awasome 12";
447 The string must be valid UTF-8, special characters can be escaped:
451 text {
454 content: "Line one\n\tIndented line two";
455 }
456 The following special characters can be escaped: \b, \f, \n, \r, \t,
460 \v, \ and ".
461
464 • Format: [-+]?[:digit:]+
465 An integer may contain any number.
469 For examples:
472 lines: 12;
475
479 • Format: [-+]?[:digit:]+(\.[:digit:]+)?
480 A real is an integer with an optional fraction.
484 For example:
487 real: 3.4;
490 The following is not valid: .3, 3. or scientific notation: 3.4e-3.
494
497 • Format: (true|false)
498 Boolean value is either true or false. This is case-sensitive.
502 For example:
505 dynamic: false;
508
512 rofi support a limited set of background-image formats.
513 • Format: url("path to image");
516 • Format: url("path to image", scale); where scale is: none,
518 both, width, height
519 • Format: linear-gradient(stop color,stop1, color, stop2 color,
521 ...);
522 • Format: linear-gradient(to direction, stop color,stop1, color,
524 stop2 color, ...); where direction is: top,left,right,bot‐
525 tom.
526 • Format: linear-gradient(angle, stop color,stop1, color, stop2
528 color, ...); Angle in deg,rad,grad (as used in color).
529 Where the path is a string, and stop color is of type color.
533
536 rofi supports the color formats as specified in the CSS standard (1,2,3
537 and some of CSS 4)
538 • Format: #{HEX}{3} (rgb)
541 • Format: #{HEX}{4} (rgba)
543 • Format: #{HEX}{6} (rrggbb)
545 • Format: #{HEX}{8} (rrggbbaa)
547 • Format: rgb[a]({INTEGER},{INTEGER},{INTEGER}[, {PERCENTAGE}])
549 • Format: rgb[a]({INTEGER}%,{INTEGER}%,{INTEGER}%[, {PERCENT‐
551 AGE}])
552 • Format: hsl[a]( {ANGLE}, {PERCENTAGE}, {PERCENTAGE} [, {PER‐
554 CENTAGE}])
555 • Format: hwb[a]( {ANGLE}, {PERCENTAGE}, {PERCENTAGE} [, {PER‐
557 CENTAGE}])
558 • Format: cmyk( {PERCENTAGE}, {PERCENTAGE}, {PERCENTAGE}, {PER‐
560 CENTAGE} [, {PERCENTAGE} ])
561 • Format: {named-color} [ / {PERCENTAGE} ]
563 The white-space format proposed in CSS4 is also supported.
567 The different values are:
570 • {HEX} is a hexadecimal number ('0-9a-f' case insensitive).
573 • {INTEGER} value can be between 0 and 255 or 0-100 when repre‐
575 senting percentage.
576 • {ANGLE} is the angle on the color wheel, can be in deg, rad,
578 grad or turn. When no unit is specified, degrees is assumed.
579 • {PERCENTAGE} can be between 0-1.0, or 0%-100%
581 • {named-color} is one of the following colors:AliceBlue, An‐
583 tiqueWhite, Aqua, Aquamarine, Azure, Beige, Bisque, Black,
584 BlanchedAlmond, Blue, BlueViolet, Brown, BurlyWood, CadetBlue,
585 Chartreuse, Chocolate, Coral, CornflowerBlue, Cornsilk, Crim‐
586 son, Cyan, DarkBlue, DarkCyan, DarkGoldenRod, DarkGray, Dark‐
587 Grey, DarkGreen, DarkKhaki, DarkMagenta, DarkOliveGreen, Dark‐
588 Orange, DarkOrchid, DarkRed, DarkSalmon, DarkSeaGreen, Dark‐
589 SlateBlue, DarkSlateGray, DarkSlateGrey, DarkTurquoise, Dark‐
590 Violet, DeepPink, DeepSkyBlue, DimGray, DimGrey, DodgerBlue,
591 FireBrick, FloralWhite, ForestGreen, Fuchsia, Gainsboro,
592 GhostWhite, Gold, GoldenRod, Gray, Grey, Green, GreenYellow,
593 HoneyDew, HotPink, IndianRed, Indigo, Ivory, Khaki, Lavender,
594 LavenderBlush, LawnGreen, LemonChiffon, LightBlue, LightCoral,
595 LightCyan, LightGoldenRodYellow, LightGray, LightGrey, Light‐
596 Green, LightPink, LightSalmon, LightSeaGreen, LightSkyBlue,
597 LightSlateGray, LightSlateGrey, LightSteelBlue, LightYellow,
598 Lime, LimeGreen, Linen, Magenta, Maroon, MediumAquaMarine,
599 MediumBlue, MediumOrchid, MediumPurple, MediumSeaGreen, Medi‐
600 umSlateBlue, MediumSpringGreen, MediumTurquoise, MediumViole‐
601 tRed, MidnightBlue, MintCream, MistyRose, Moccasin, Nava‐
602 joWhite, Navy, OldLace, Olive, OliveDrab, Orange, OrangeRed,
603 Orchid, PaleGoldenRod, PaleGreen, PaleTurquoise, PaleViole‐
604 tRed, PapayaWhip, PeachPuff, Peru, Pink, Plum, PowderBlue,
605 Purple, RebeccaPurple, Red, RosyBrown, RoyalBlue, SaddleBrown,
606 Salmon, SandyBrown, SeaGreen, SeaShell, Sienna, Silver, Sky‐
607 Blue, SlateBlue, SlateGray, SlateGrey, Snow, SpringGreen,
608 SteelBlue, Tan, Teal, Thistle, Tomato, Turquoise, Violet,
609 Wheat, White, WhiteSmoke, Yellow, YellowGreen,transparent
610 For example:
614 background-color: #FF0000;
617 border-color: rgba(0,0,1, 0.5);
618 text-color: SeaGreen;
619 or
623 background-color: transparent;
626 text-color: Black;
627
631 • Format: (bold|italic|underline|strikethrough|none)
632 Text style indicates how the highlighted text is emphasized. None indi‐
636 cates that no emphasis should be applied.
637 • bold: make the text thicker then the surrounding text.
640 • italic: put the highlighted text in script type (slanted).
642 • underline: put a line under the text.
644 • strikethrough: put a line through the text.
646 The following options are available on pango 1.50.0 and up:
650 • uppercase: Uppercase the text.
653 • lowercase: Lowercase the text.
655 The following option is disabled as pango crashes on this if there is
659 eel
660 upsizing or wrapping. This will be re-enabled once fixed:
661 • capitalize: Capitalize the text.
664
668 • Format: (dash|solid)
669 Indicates how a line should be drawn. It currently supports:
673 * dash: a dashed line, where the gap is the same width as the dash
674 * solid: a solid line
675
678 • Format: {Integer}px
679 • Format: {Real}em
681 • Format: {Real}ch
683 • Format: {Real}%
685 • Format: {Integer}mm
687 A distance can be specified in 3 different units:
691 • px: Screen pixels.
694 • em: Relative to text height.
696 • ch: Relative to width of a single number.
698 • mm: Actual size in millimeters (based on dpi).
700 • %: Percentage of the monitor size.
702 Distances used in the horizontal direction use the monitor width. Dis‐
706 tances in the vertical direction use the monitor height. For example:
707 padding: 10%;
710 On a full-HD (1920x1080) monitor, it defines a padding of 192 pixels on
714 the left and right side and 108 pixels on the top and bottom.
715 Calculating sizes
718 Rofi supports some maths in calculating sizes. For this it uses the CSS
719 syntax:
720 width: calc( 100% - 37px );
723 width: calc( 20% min 512 );
727 It supports the following operations:
731 • + : Add
734 • - : Subtract
736 • / : Divide
738 • * : Multiply
740 • % : Modulo
742 • min : Minimum of lvalue or rvalue;
744 • max : Maximum of lvalue or rvalue;
746 • floor : Round down lvalue to the next multiple of rvalue
748 • ceil : Round up lvalue to the next multiple of rvalue
750 • round : Round lvalue to the next multiple of rvalue
752 It uses the C precedence ordering.
756
759 • Format: {Integer}
760 • Format: {Distance}
762 • Format: {Distance} {Distance}
764 • Format: {Distance} {Distance} {Distance}
766 • Format: {Distance} {Distance} {Distance} {Distance}
768 If no unit is specified, pixels are assumed.
772 The different number of fields in the formats are parsed like:
775 • 1 field: all
778 • 2 fields: top&bottom left&right
780 • 3 fields: top, left&right, bottom
782 • 4 fields: top, right, bottom, left
784
788 • Format: {Integer}
789 • Format: {Distance}
791 • Format: {Distance} {Distance}
793 • Format: {Distance} {Distance} {Distance}
795 • Format: {Distance} {Distance} {Distance} {Distance}
797 • Format: {Distance} {Line style}
799 • Format: {Distance} {Line style} {Distance} {Line style}
801 • Format: {Distance} {Line style} {Distance} {Line style} {Dis‐
803 tance} {Line style}
804 • Format: {Distance} {Line style} {Distance} {Line style} {Dis‐
806 tance} {Line style} {Distance} {Line style}
807 Borders are identical to padding, except that each distance field has a
811 line style property.
812 When no unit is specified, pixels are assumed.
815
819 Indicate a place on the window/monitor.
820 ┌─────────────┬─────────────┬─────────────┐
823 │ north west │ north │ north east │
824 ├─────────────┼─────────────┼─────────────┤
825 │ west │ center │ east │
826 ├─────────────┼─────────────┼─────────────┤
827 │ south west │ south │ south east │
828 └─────────────┴─────────────┴─────────────┘
829 • Format: (center|east|north|west|south|north east|north
833 west|south west|south east)
834
838 It is possible to hide widgets:
839 inputbar {
842 enabled: false;
843 }
844
848 • Format: @{PROPERTY NAME}
849 A reference can point to another reference. Currently, the maximum num‐
853 ber of redirects is 20. A property always refers to another property.
854 It cannot be used for a subpart of the property. For example, this is
855 not valid:
856 highlight: bold @pink;
859 But this is:
863 * {
866 myhigh: bold #FAA;
867 }
868 window {
870 highlight: @myhigh;
871 }
872 • Format: var(PROPERTY NAME, DEFAULT)
876 A reference can point to another reference. Currently, the maximum num‐
880 ber of redirects is 20. A property always refers to another property.
881 It cannot be used for a subpart of the property.
882 Example:
885 window {
888 width: var( width, 30%);
889 }
890 If the property width is set globally (*{}) that value is used, if the
894 property width is not set, the default value is used.
895
898 • Format: (horizontal|vertical)
899 Specify the orientation of the widget.
903
906 • Format: (default|pointer|text)
907 Specify the type of mouse cursor that is set when the mouse pointer is
911 over the widget.
912
915 • Format: [ keyword, keyword ]
916 A list starts with a '[' and ends with a ']'. The entries in the list
920 are comma-separated. The keyword in the list refers to an widget name.
921
924 • Format: [ value, value, ... ]
925 An list starts with a '[' and ends with a ']'. The entries in the list
929 are comma-separated.
930
933 • Format: ${:alnum:}
934 This will parse the environment variable as the property value. (that
938 then can be any of the above types). The environment variable should
939 be an alphanumeric string without white-space.
940 * {
943 background-color: ${BG};
944 }
945 • Format: env(ENVIRONMENT, default)
949 This will parse the environment variable as the property value. (that
953 then can be any of the above types). The environment variable should
954 be an alphanumeric string without white-space. If the environment
955 value is not found, the default value is used.
956 window {
959 width: env(WIDTH, 40%);
960 }
961 If environment WIDTH is set, then that value is parsed, otherwise the
965 default value (40%).
966
969 • Format: inherit
970 Inherits the property from its parent widget.
974 mainbox {
977 border-color: inherit;
978 }
979
983 Element paths exists of two parts, the first part refers to the actual
984 widget by name. Some widgets have an extra state.
985 For example:
988 element selected {
991 }
992 Here element selected is the name of the widget, selected is the state
996 of the widget.
997 The difference between dots and spaces is purely cosmetic. These are
1000 all the same:
1001 element .selected {
1004 element.selected {
1006 }
1007 element selected {
1008 }
1009
1014 The current widgets available in rofi:
1015 • window
1018 • overlay: the overlay widget.
1020 • mainbox: The mainbox box.
1022 • inputbar: The input bar box.
1024 • box: the horizontal @box packing the widgets
1026 • case-indicator: the case/sort indicator @textbox
1028 • prompt: the prompt @textbox
1030 • entry: the main entry @textbox
1032 • num-rows: Shows the total number of rows.
1034 • num-filtered-rows: Shows the total number of rows after
1036 filtering.
1037 • textbox-current-entry: Shows the text of the currently se‐
1039 lected entry.
1040 • icon-current-entry: Shows the icon of the currently se‐
1042 lected entry.
1043 • listview: The listview.
1047 • scrollbar: the listview scrollbar
1049 • element: a box in the listview holding the entries
1051 • element-icon: the widget in the listview's entry showing
1053 the (optional) icon
1054 • element-index: the widget in the listview's entry key‐
1056 bindable index (1,2,3..0)
1057 • element-text: the widget in the listview's entry showing
1059 the text.
1060 • mode-switcher: the main horizontal @box packing the buttons.
1066 • button: the buttons @textbox for each mode
1068 • message: The container holding the textbox.
1072 • textbox: the message textbox
1074 Note that these path names match the default theme. Themes that provide
1082 a custom layout will have different elements, and structure.
1083
1086 State: State of widget
1087 Optional flag(s) indicating state of the widget, used for theming.
1090 These are appended after the name or class of the widget.
1093 Example:
1096 button selected.normal { }
1097 element selected.urgent { }
1100 Currently only the entrybox and scrollbar have states:
1103 Entrybox:
1106 {visible modifier}.{state}
1107 Where visible modifier can be:
1110 * normal: no modification
1111 * selected: the entry is selected/highlighted by user
1112 * alternate: the entry is at an alternating row (uneven row)
1113 Where state is:
1116 * normal: no modification
1117 * urgent: this entry is marked urgent
1118 * active: this entry is marked active
1119 These can be mixed.
1122 Example:
1125 nametotextbox selected.active {
1128 background-color: #003642;
1129 text-color: #008ed4;
1130 }
1131 Sets all selected textboxes marked active to the given text and back‐
1135 ground color. Note that a state modifies the original element, it
1136 therefore contains all the properties of that element.
1137 Scrollbar
1140 The scrollbar uses the handle state when drawing the small scrollbar
1141 handle. This allows the colors used for drawing the handle to be set
1142 independently.
1143
1146 The following properties are currently supported:
1147 all widgets:
1150 • enabled: enable/disable rendering of the widget
1151 • padding: padding Padding on the inside of the widget
1153 • margin: padding Margin on the outside of the widget
1155 • border: border Border around the widget (between
1157 padding and margin)/
1158 • border-radius: padding Sets a radius on the corners of the
1160 borders.
1161 • background-color: color Background color
1163 • background-image: image Background image
1165 • border-color: color Color of the border
1167 • cursor: cursor Type of mouse cursor that is set
1169 when the mouse pointer is hovered over the widget.
1170 window:
1174 • font: string The font used in the window
1175 • transparency: string Indicating if transparency should be
1177 used and what type: real - True transparency. Only works with
1178 a compositor. background - Take a screenshot of the back‐
1179 ground image and use that. screenshot - Take a screenshot of
1180 the screen and use that. Path to png file - Use an image.
1181 • location: position The place of the anchor on the moni‐
1183 tor
1184 • anchor: anchor The anchor position on the window
1186 • fullscreen: boolean Window is fullscreen.
1188 • width: distance The width of the window
1190 • x-offset: distance
1192 • y-offset: distance The offset of the window to the an‐
1194 chor point, allowing you to push the window left/right/up/down
1195 scrollbar:
1199 • background-color: color
1200 • handle-width: distance
1202 • handle-color: color
1204 • border-color: color
1206 box:
1210 • orientation: orientation
1211 Set the direction the elements are packed.
1212 • spacing: distance
1214 Distance between the packed elements.
1215 textbox:
1219 • background-color: color
1220 • border-color: the color used for the border around the
1222 widget.
1223 • font: the font used by this textbox (string).
1225 • str/content: the string to display by this textbox (string).
1227 • vertical-align: Vertical alignment of the text. A number
1229 between 0 (top) and 1 (bottom).
1230 • horizontal-align: Horizontal alignment of the text. A number
1232 between 0 (left) and 1 (right).
1233 • text-color: the text color to use.
1235 • text-transform: text style {color} for the whole text.
1237 • highlight: text style {color}. color is optional,
1239 multiple highlight styles can be added like: bold underline
1240 italic #000000; This option is only available on the element-
1241 text widget.
1242 • width: override the desired width for the textbox.
1244 • content: Set the displayed text (String).
1246 • placeholder: Set the displayed text (String) when noth‐
1248 ing is entered.
1249 • placeholder-markup: If true, placeholder text supports
1251 pango markup for stylizing.
1252 • placeholder-color: Color of the placeholder text.
1254 • blink: Enable/Disable blinking on an input textbox
1256 (Boolean).
1257 • markup: Force markup on, beware that only valid
1259 pango markup strings are shown.
1260 • tab-stops: array of distances Set the location of tab
1262 stops by their distance from the beginning of the line. Each
1263 distance should be greater than the previous one. The text
1264 appears to the right of the tab stop position (other align‐
1265 ments are not supported yet).
1266 listview:
1270 • columns: integer Number of columns to show (at least
1271 1)
1272 • fixed-height: boolean Always show lines rows, even if fewer
1274 elements are available.
1275 • dynamic: boolean True if the size should change when
1277 filtering the list, False if it should keep the original
1278 height.
1279 • scrollbar: boolean If the scrollbar should be en‐
1281 abled/disabled.
1282 • scrollbar-width: distance Width of the scrollbar
1284 • cycle: boolean When navigating, it should wrap
1286 around
1287 • spacing: distance Spacing between the elements (both
1289 vertical and horizontal)
1290 • lines: integer Number of rows to show in the list
1292 view.
1293 • layout: orientation Indicate how elements are
1295 stacked. Horizontal implements the dmenu style.
1296 • reverse: boolean Reverse the ordering (top down to
1298 bottom up).
1299 • flow: orientation The order the elements are layed
1301 out. Vertical is the original 'column' view.
1302 • fixed-columns: boolean Do not reduce the number of columns
1304 shown when number of visible elements is not enough to fill
1305 them all.
1306 • require-input: boolean Listview requires user input to show
1308 up.
1309 Each element is a box called element. Each element can contain an ele‐
1313 ment-icon and element-text.
1314 listview text highlight:
1317 The element-text widget in the listview is the one used to show the
1318 text. On this widget set the highlight property (only place this prop‐
1319 erty is used) to change the style of highlighting. The highlight prop‐
1320 erty consist of the text-style property and a color.
1321 To disable highlighting:
1324 element-text {
1327 highlight: None;
1328 }
1329 To set to red underlined:
1333 element-text {
1336 highlight: underline red;
1337 }
1338
1342 The new format allows the layout of the rofi window to be tweaked ex‐
1343 tensively. For each widget, the themer can specify padding, margin,
1344 border, font, and more. It even allows, as an advanced feature, to
1345 pack widgets in a custom structure.
1346 Basic structure
1349 The whole view is made out of boxes that pack other boxes or widgets.
1350 The box can be vertical or horizontal. This is loosely inspired by GTK
1351 ⟨http://gtk.org/⟩.
1352 The current layout of rofi is structured as follows:
1355 ┌────────────────────────────────────────────────────────────────────────────────────┐
1358 │ window {BOX:vertical} │
1359 │ ┌───────────────────────────────────────────────────────────────────────────────┐ │
1360 │ │ mainbox {BOX:vertical} │ │
1361 │ │ ┌───────────────────────────────────────────────────────────────────────────┐ │ │
1362 │ │ │ inputbar {BOX:horizontal} │ │ │
1363 │ │ │ ┌─────────┐ ┌─┐ ┌───────────────────────────────┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ │ │ │
1364 │ │ │ │ prompt │ │:│ │ entry │ │#fr│ │ / │ │#ns│ │ci │ │ │ │
1365 │ │ │ └─────────┘ └─┘ └───────────────────────────────┘ └───┘ └───┘ └───┘ └───┘ │ │ │
1366 │ │ └───────────────────────────────────────────────────────────────────────────┘ │ │
1367 │ │ │ │
1368 │ │ ┌───────────────────────────────────────────────────────────────────────────┐ │ │
1369 │ │ │ message │ │ │
1370 │ │ │ ┌───────────────────────────────────────────────────────────────────────┐ │ │ │
1371 │ │ │ │ textbox │ │ │ │
1372 │ │ │ └───────────────────────────────────────────────────────────────────────┘ │ │ │
1373 │ │ └───────────────────────────────────────────────────────────────────────────┘ │ │
1374 │ │ │ │
1375 │ │ ┌───────────────────────────────────────────────────────────────────────────┐ │ │
1376 │ │ │ listview │ │ │
1377 │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │
1378 │ │ │ │ element │ │ │ │
1379 │ │ │ │ ┌─────────────────┐ ┌─────────────────────────────────────────────┐ │ │ │ │
1380 │ │ │ │ │element─icon │ │element─text │ │ │ │ │
1381 │ │ │ │ └─────────────────┘ └─────────────────────────────────────────────┘ │ │ │ │
1382 │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │
1383 │ │ └───────────────────────────────────────────────────────────────────────────┘ │ │
1384 │ │ │ │
1385 │ │ ┌───────────────────────────────────────────────────────────────────────────┐ │ │
1386 │ │ │ mode─switcher {BOX:horizontal} │ │ │
1387 │ │ │ ┌───────────────┐ ┌───────────────┐ ┌──────────────┐ ┌───────────────┐ │ │ │
1388 │ │ │ │ Button │ │ Button │ │ Button │ │ Button │ │ │ │
1389 │ │ │ └───────────────┘ └───────────────┘ └──────────────┘ └───────────────┘ │ │ │
1390 │ │ └───────────────────────────────────────────────────────────────────────────┘ │ │
1391 │ └───────────────────────────────────────────────────────────────────────────────┘ │
1392 └────────────────────────────────────────────────────────────────────────────────────┘
1393 • ci is the case-indicator
1399 • fr is the num-filtered-rows
1401 • ns is the num-rows
1403 Error message structure
1408 ┌──────────────────────────────────────────────────────────────────────────────────┐
1409 │ window {BOX:vertical} │
1410 │ ┌─────────────────────────────────────────────────────────────────────────────┐ │
1411 │ │ error─message {BOX:vertical} │ │
1412 │ │ ┌────────────────────────────────────────────────────────────────────────┐ │ │
1413 │ │ │ textbox │ │ │
1414 │ │ └────────────────────────────────────────────────────────────────────────┘ │ │
1415 │ └─────────────────────────────────────────────────────────────────────────────┘ │
1416 └──────────────────────────────────────────────────────────────────────────────────┘
1417 Advanced layout
1422 The layout of rofi can be tweaked by packing the 'fixed' widgets in a
1423 custom structure.
1424 The following widgets are fixed, as they provide core rofi functional‐
1427 ity:
1428 • prompt
1431 • entry
1433 • overlay
1435 • case-indicator
1437 • message
1439 • listview
1441 • mode-switcher
1443 • num-rows
1445 • num-filtered-rows
1447 The following keywords are defined and can be used to automatically
1451 pack a subset of the widgets. These are used in the default theme as
1452 depicted in the figure above.
1453 • mainbox Packs: inputbar, message, listview, mode-switcher
1456 • inputbar Packs: prompt,entry,case-indicator
1458 Any widget name starting with textbox is a textbox widget, others are
1462 box widgets and can pack other widgets.
1463 There are several special widgets that can be used by prefixing the
1466 name of the widget:
1467 textbox
1470 This is a read-only textbox widget. The displayed string can be set
1471 with content.
1472 Example:
1475 textbox-custom {
1478 expand: false;
1479 content: "My Message";
1480 }
1481 Icon
1485 This is an icon widget. The displayed icon can be set with filename and
1486 size with size. If the property action is set, it acts as a button.
1487 action can be set to a keybinding name and completes that action. (see
1488 rofi -show keys for a list).
1489 If the squared property is set to false the widget height and width are
1492 not forced to be equal.
1493 Example:
1496 icon-paste {
1499 expand: false;
1500 filename: "gtk-paste";
1501 size: 24;
1502 vertical-align: 0.5;
1503 action: "kb-primary-paste";
1504 }
1505 button
1509 This is a textbox widget that can have a 'clickable' action. The ac‐
1510 tion can be set to: keybinding: accepts a keybinding name and completes
1511 that action. (see rofi -show keys for a list).
1512 button-paste {
1515 expand: false;
1516 content: "My Clickable Message";
1517 vertical-align: 0.5;
1518 action: "kb-primary-paste";
1519 }
1520 Children
1524 To specify children, set the children property (this always happens on
1525 the box child, see example below):
1526 inputbar {
1529 children: [prompt,entry,overlay,case-indicator];
1530 }
1531 The theme needs to be updated to match the hierarchy specified.
1535 Below is an example of a theme emulating dmenu:
1538 * {
1541 background-color: Black;
1542 text-color: White;
1543 border-color: White;
1544 font: "Times New Roman 12";
1545 }
1546 window {
1548 anchor: north;
1549 location: north;
1550 width: 100%;
1551 padding: 4px;
1552 children: [ horibox ];
1553 }
1554 horibox {
1556 orientation: horizontal;
1557 children: [ prompt, entry, listview ];
1558 }
1559 listview {
1561 layout: horizontal;
1562 spacing: 5px;
1563 lines: 10;
1564 }
1565 entry {
1567 expand: false;
1568 width: 10em;
1569 }
1570 element {
1572 padding: 0px 2px;
1573 }
1574 element selected {
1575 background-color: SteelBlue;
1576 }
1577 Padding and margin
1581 Just like CSS, rofi uses the box model for each widget.
1582 ┌──────────────────────────────────────────────────────────────────┐
1585 │ margin │
1586 │ ┌────────────────────────────────────────────────────────────┐ │
1587 │ │ border │ │
1588 │ │ ┌────────────────────────────────────────────────────────┐ │ │
1589 │ │ │ padding │ │ │
1590 │ │ │ ┌────────────────────────────────────────────────────┐ │ │ │
1591 │ │ │ │ content │ │ │ │
1592 │ │ │ └────────────────────────────────────────────────────┘ │ │ │
1593 │ │ └────────────────────────────────────────────────────────┘ │ │
1594 │ └────────────────────────────────────────────────────────────┘ │
1595 └──────────────────────────────────────────────────────────────────┘
1596 Explanation of the different parts:
1600 • Content - The content of the widget.
1603 • Padding - Clears an area around the widget. The padding shows
1605 the background color of the widget.
1606 • Border - A border that goes around the padding and content.
1608 The border use the border-color of the widget.
1609 • Margin - Clears an area outside the border. The margin is
1611 transparent.
1612 The box model allows us to add a border around elements, and to define
1616 space between elements.
1617 The size of each margin, border, and padding can be set. For the bor‐
1620 der, a linestyle and radius can be set.
1621 Spacing
1624 Widgets that can pack more then one child widget (currently box and
1625 listview) have the spacing property. This property sets the distance
1626 between the packed widgets (both horizontally and vertically).
1627 ┌───────────────────────────────────────┐
1630 │ ┌────────┐ s ┌────────┐ s ┌────────┐ │
1631 │ │ child │ p │ child │ p │ child │ │
1632 │ │ │ a │ │ a │ │ │
1633 │ │ │ c │ │ c │ │ │
1634 │ │ │ i │ │ i │ │ │
1635 │ │ │ n │ │ n │ │ │
1636 │ └────────┘ g └────────┘ g └────────┘ │
1637 └───────────────────────────────────────┘
1638 Advanced box packing
1642 More dynamic spacing can be achieved by adding dummy widgets, for exam‐
1643 ple to make one widget centered:
1644 ┌────────────────────────────────────────────────────┐
1647 │ ┌───────────────┐ ┌────────┐ ┌───────────────┐ │
1648 │ │ dummy │ │ child │ │ dummy │ │
1649 │ │ expand: true; │ │ │ │ expand: true; │ │
1650 │ │ │ │ │ │ │ │
1651 │ │ │ │ │ │ │ │
1652 │ │ │ │ │ │ │ │
1653 │ └───────────────┘ └────────┘ └───────────────┘ │
1654 └────────────────────────────────────────────────────┘
1655 If both dummy widgets are set to expand, child will be centered. De‐
1659 pending on the expand flag of child the remaining space will be equally
1660 divided between both dummy and child widget (expand enabled), or both
1661 dummy widgets (expand disabled).
1662
1665 To get debug information from the parser, run rofi like:
1666 G_MESSAGES_DEBUG=Parser rofi -show run
1669 Syntax errors are shown in a popup and printed out to command line with
1673 the above command.
1674 To see the elements queried during running, run:
1677 G_MESSAGES_DEBUG=Theme rofi -show run
1680 To test minor changes, part of the theme can be passed on the command
1684 line, for example to set it to full-screen:
1685 rofi -theme-str 'window { fullscreen:true;}' -show run
1688 Another syntax to modify theme properties is:
1692 rofi -theme+window+fullscreen true -show run
1695 To print the current theme, run:
1699 rofi -dump-theme
1702
1706 Parts of the theme can be conditionally loaded, like the CSS @media op‐
1707 tion.
1708 @media ( min-width: 120 ) {
1711 }
1713 It supports the following keys as constraint:
1717 • min-width: load when width is bigger or equal then
1720 value.
1721 • max-width: load when width is smaller then value.
1723 • min-height: load when height is bigger or equal then
1725 value.
1726 • max-height: load when height is smaller then value.
1728 • min-aspect-ratio load when aspect ratio is over value.
1730 • max-aspect-ratio: load when aspect ratio is under value.
1732 • monitor-id: The monitor id, see rofi -help for id's.
1734 • enabled: Boolean option to enable. Supports environ‐
1736 ment variable.
1737 @media takes an integer number or a fraction, for integer number px can
1741 be added.
1742 @media ( min-width: 120 px ) {
1745 }
1747 @media ( enabled: env(DO_LIGHT, false ) {
1751 }
1753
1757 Rofi uses pango ⟨https://pango.gnome.org/⟩ for font rendering. The font
1758 should be specified in a format that pango understands. This normally
1759 is the font name followed by the font size. For example:
1760 mono 18
1763 Or
1767 FontAwesome 22
1770
1774 Rofi supports 3 ways of specifying an icon:
1775 • Filename
1778 • icon-name, this is looked up via the icon-theme.
1780 • Markup String. It renders a string as an icon.
1782 For the first two options, GdkPixbuf is used to open and render the
1786 icons. This in general gives support for most required image formats.
1787 For the string option it uses Pango to render the string. The string
1788 needs to start with a <span tag, that allows you to set color and font.
1789 Markup string:
1792 echo -en "testing\0icon\x1f<span color='red'>⏻</span>" | ./rofi -dmenu
1795 Getting supported icon formats:
1799 G_MESSAGES_DEBUG=Helpers.IconFetcher rofi
1802 This uses the debug framework and prints out a list of supported image
1806 file extensions.
1807
1810 The rasi file format offers two methods of including other files. This
1811 can be used to modify existing themes, or have multiple variations on a
1812 theme.
1813 • import: Import and parse a second file.
1816 • theme: Discard theme, and load file as a fresh theme.
1818 Syntax:
1822 @import "myfile"
1825 @theme "mytheme"
1826 The specified file can either by name, filename,full path.
1830 If a filename is provided, it will try to resolve it in the following
1833 order:
1834 • ${XDG_CONFIG_HOME}/rofi/themes/
1837 • ${XDG_CONFIG_HOME}/rofi/
1839 • ${XDG_DATA_HOME}/rofi/themes/
1841 • ${INSTALL PREFIX}/share/rofi/themes/
1843 A name is resolved as a filename by appending the .rasi extension.
1847
1850 Several examples are installed together with rofi. These can be found
1851 in {datadir}/rofi/themes/, where {datadir} is the install path of rofi
1852 data. When installed using a package manager, this is usually:
1853 /usr/share/.
1854
1857 rofi(1), rofi-script(5), rofi-theme-selector(1)
1858 rofi-theme ROFI-THEME(5)