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-color: Color of the placeholder text.
1251 • blink: Enable/Disable blinking on an input textbox
1253 (Boolean).
1254 • markup: Force markup on, beware that only valid
1256 pango markup strings are shown.
1257 • tab-stops: array of distances Set the location of tab
1259 stops by their distance from the beginning of the line. Each
1260 distance should be greater than the previous one. The text
1261 appears to the right of the tab stop position (other align‐
1262 ments are not supported yet).
1263 listview:
1267 • columns: integer Number of columns to show (at least
1268 1)
1269 • fixed-height: boolean Always show lines rows, even if fewer
1271 elements are available.
1272 • dynamic: boolean True if the size should change when
1274 filtering the list, False if it should keep the original
1275 height.
1276 • scrollbar: boolean If the scrollbar should be en‐
1278 abled/disabled.
1279 • scrollbar-width: distance Width of the scrollbar
1281 • cycle: boolean When navigating, it should wrap
1283 around
1284 • spacing: distance Spacing between the elements (both
1286 vertical and horizontal)
1287 • lines: integer Number of rows to show in the list
1289 view.
1290 • layout: orientation Indicate how elements are
1292 stacked. Horizontal implements the dmenu style.
1293 • reverse: boolean Reverse the ordering (top down to
1295 bottom up).
1296 • flow: orientation The order the elements are layed
1298 out. Vertical is the original 'column' view.
1299 • fixed-columns: boolean Do not reduce the number of columns
1301 shown when number of visible elements is not enough to fill
1302 them all.
1303 • require-input: boolean Listview requires user input to show
1305 up.
1306 Each element is a box called element. Each element can contain an ele‐
1310 ment-icon and element-text.
1311 listview text highlight:
1314 The element-text widget in the listview is the one used to show the
1315 text. On this widget set the highlight property (only place this prop‐
1316 erty is used) to change the style of highlighting. The highlight prop‐
1317 erty consist of the text-style property and a color.
1318 To disable highlighting:
1321 element-text {
1324 highlight: None;
1325 }
1326 To set to red underlined:
1330 element-text {
1333 highlight: underline red;
1334 }
1335
1339 The new format allows the layout of the rofi window to be tweaked ex‐
1340 tensively. For each widget, the themer can specify padding, margin,
1341 border, font, and more. It even allows, as an advanced feature, to
1342 pack widgets in a custom structure.
1343 Basic structure
1346 The whole view is made out of boxes that pack other boxes or widgets.
1347 The box can be vertical or horizontal. This is loosely inspired by GTK
1348 ⟨http://gtk.org/⟩.
1349 The current layout of rofi is structured as follows:
1352 ┌────────────────────────────────────────────────────────────────────────────────────┐
1355 │ window {BOX:vertical} │
1356 │ ┌───────────────────────────────────────────────────────────────────────────────┐ │
1357 │ │ mainbox {BOX:vertical} │ │
1358 │ │ ┌───────────────────────────────────────────────────────────────────────────┐ │ │
1359 │ │ │ inputbar {BOX:horizontal} │ │ │
1360 │ │ │ ┌─────────┐ ┌─┐ ┌───────────────────────────────┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ │ │ │
1361 │ │ │ │ prompt │ │:│ │ entry │ │#fr│ │ / │ │#ns│ │ci │ │ │ │
1362 │ │ │ └─────────┘ └─┘ └───────────────────────────────┘ └───┘ └───┘ └───┘ └───┘ │ │ │
1363 │ │ └───────────────────────────────────────────────────────────────────────────┘ │ │
1364 │ │ │ │
1365 │ │ ┌───────────────────────────────────────────────────────────────────────────┐ │ │
1366 │ │ │ message │ │ │
1367 │ │ │ ┌───────────────────────────────────────────────────────────────────────┐ │ │ │
1368 │ │ │ │ textbox │ │ │ │
1369 │ │ │ └───────────────────────────────────────────────────────────────────────┘ │ │ │
1370 │ │ └───────────────────────────────────────────────────────────────────────────┘ │ │
1371 │ │ │ │
1372 │ │ ┌───────────────────────────────────────────────────────────────────────────┐ │ │
1373 │ │ │ listview │ │ │
1374 │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │
1375 │ │ │ │ element │ │ │ │
1376 │ │ │ │ ┌─────────────────┐ ┌─────────────────────────────────────────────┐ │ │ │ │
1377 │ │ │ │ │element─icon │ │element─text │ │ │ │ │
1378 │ │ │ │ └─────────────────┘ └─────────────────────────────────────────────┘ │ │ │ │
1379 │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │
1380 │ │ └───────────────────────────────────────────────────────────────────────────┘ │ │
1381 │ │ │ │
1382 │ │ ┌───────────────────────────────────────────────────────────────────────────┐ │ │
1383 │ │ │ mode─switcher {BOX:horizontal} │ │ │
1384 │ │ │ ┌───────────────┐ ┌───────────────┐ ┌──────────────┐ ┌───────────────┐ │ │ │
1385 │ │ │ │ Button │ │ Button │ │ Button │ │ Button │ │ │ │
1386 │ │ │ └───────────────┘ └───────────────┘ └──────────────┘ └───────────────┘ │ │ │
1387 │ │ └───────────────────────────────────────────────────────────────────────────┘ │ │
1388 │ └───────────────────────────────────────────────────────────────────────────────┘ │
1389 └────────────────────────────────────────────────────────────────────────────────────┘
1390 • ci is the case-indicator
1396 • fr is the num-filtered-rows
1398 • ns is the num-rows
1400 Error message structure
1405 ┌──────────────────────────────────────────────────────────────────────────────────┐
1406 │ window {BOX:vertical} │
1407 │ ┌─────────────────────────────────────────────────────────────────────────────┐ │
1408 │ │ error─message {BOX:vertical} │ │
1409 │ │ ┌────────────────────────────────────────────────────────────────────────┐ │ │
1410 │ │ │ textbox │ │ │
1411 │ │ └────────────────────────────────────────────────────────────────────────┘ │ │
1412 │ └─────────────────────────────────────────────────────────────────────────────┘ │
1413 └──────────────────────────────────────────────────────────────────────────────────┘
1414 Advanced layout
1419 The layout of rofi can be tweaked by packing the 'fixed' widgets in a
1420 custom structure.
1421 The following widgets are fixed, as they provide core rofi functional‐
1424 ity:
1425 • prompt
1428 • entry
1430 • overlay
1432 • case-indicator
1434 • message
1436 • listview
1438 • mode-switcher
1440 • num-rows
1442 • num-filtered-rows
1444 The following keywords are defined and can be used to automatically
1448 pack a subset of the widgets. These are used in the default theme as
1449 depicted in the figure above.
1450 • mainbox Packs: inputbar, message, listview, mode-switcher
1453 • inputbar Packs: prompt,entry,case-indicator
1455 Any widget name starting with textbox is a textbox widget, others are
1459 box widgets and can pack other widgets.
1460 There are several special widgets that can be used by prefixing the
1463 name of the widget:
1464 textbox
1467 This is a read-only textbox widget. The displayed string can be set
1468 with content.
1469 Example:
1472 textbox-custom {
1475 expand: false;
1476 content: "My Message";
1477 }
1478 Icon
1482 This is an icon widget. The displayed icon can be set with filename and
1483 size with size. If the property action is set, it acts as a button.
1484 action can be set to a keybinding name and completes that action. (see
1485 rofi -show keys for a list).
1486 If the squared property is set to false the widget height and width are
1489 not forced to be equal.
1490 Example:
1493 icon-paste {
1496 expand: false;
1497 filename: "gtk-paste";
1498 size: 24;
1499 vertical-align: 0.5;
1500 action: "kb-primary-paste";
1501 }
1502 button
1506 This is a textbox widget that can have a 'clickable' action. The ac‐
1507 tion can be set to: keybinding: accepts a keybinding name and completes
1508 that action. (see rofi -show keys for a list).
1509 button-paste {
1512 expand: false;
1513 content: "My Clickable Message";
1514 vertical-align: 0.5;
1515 action: "kb-primary-paste";
1516 }
1517 Children
1521 To specify children, set the children property (this always happens on
1522 the box child, see example below):
1523 inputbar {
1526 children: [prompt,entry,overlay,case-indicator];
1527 }
1528 The theme needs to be updated to match the hierarchy specified.
1532 Below is an example of a theme emulating dmenu:
1535 * {
1538 background-color: Black;
1539 text-color: White;
1540 border-color: White;
1541 font: "Times New Roman 12";
1542 }
1543 window {
1545 anchor: north;
1546 location: north;
1547 width: 100%;
1548 padding: 4px;
1549 children: [ horibox ];
1550 }
1551 horibox {
1553 orientation: horizontal;
1554 children: [ prompt, entry, listview ];
1555 }
1556 listview {
1558 layout: horizontal;
1559 spacing: 5px;
1560 lines: 10;
1561 }
1562 entry {
1564 expand: false;
1565 width: 10em;
1566 }
1567 element {
1569 padding: 0px 2px;
1570 }
1571 element selected {
1572 background-color: SteelBlue;
1573 }
1574 Padding and margin
1578 Just like CSS, rofi uses the box model for each widget.
1579 ┌──────────────────────────────────────────────────────────────────┐
1582 │ margin │
1583 │ ┌────────────────────────────────────────────────────────────┐ │
1584 │ │ border │ │
1585 │ │ ┌────────────────────────────────────────────────────────┐ │ │
1586 │ │ │ padding │ │ │
1587 │ │ │ ┌────────────────────────────────────────────────────┐ │ │ │
1588 │ │ │ │ content │ │ │ │
1589 │ │ │ └────────────────────────────────────────────────────┘ │ │ │
1590 │ │ └────────────────────────────────────────────────────────┘ │ │
1591 │ └────────────────────────────────────────────────────────────┘ │
1592 └──────────────────────────────────────────────────────────────────┘
1593 Explanation of the different parts:
1597 • Content - The content of the widget.
1600 • Padding - Clears an area around the widget. The padding shows
1602 the background color of the widget.
1603 • Border - A border that goes around the padding and content.
1605 The border use the border-color of the widget.
1606 • Margin - Clears an area outside the border. The margin is
1608 transparent.
1609 The box model allows us to add a border around elements, and to define
1613 space between elements.
1614 The size of each margin, border, and padding can be set. For the bor‐
1617 der, a linestyle and radius can be set.
1618 Spacing
1621 Widgets that can pack more then one child widget (currently box and
1622 listview) have the spacing property. This property sets the distance
1623 between the packed widgets (both horizontally and vertically).
1624 ┌───────────────────────────────────────┐
1627 │ ┌────────┐ s ┌────────┐ s ┌────────┐ │
1628 │ │ child │ p │ child │ p │ child │ │
1629 │ │ │ a │ │ a │ │ │
1630 │ │ │ c │ │ c │ │ │
1631 │ │ │ i │ │ i │ │ │
1632 │ │ │ n │ │ n │ │ │
1633 │ └────────┘ g └────────┘ g └────────┘ │
1634 └───────────────────────────────────────┘
1635 Advanced box packing
1639 More dynamic spacing can be achieved by adding dummy widgets, for exam‐
1640 ple to make one widget centered:
1641 ┌────────────────────────────────────────────────────┐
1644 │ ┌───────────────┐ ┌────────┐ ┌───────────────┐ │
1645 │ │ dummy │ │ child │ │ dummy │ │
1646 │ │ expand: true; │ │ │ │ expand: true; │ │
1647 │ │ │ │ │ │ │ │
1648 │ │ │ │ │ │ │ │
1649 │ │ │ │ │ │ │ │
1650 │ └───────────────┘ └────────┘ └───────────────┘ │
1651 └────────────────────────────────────────────────────┘
1652 If both dummy widgets are set to expand, child will be centered. De‐
1656 pending on the expand flag of child the remaining space will be equally
1657 divided between both dummy and child widget (expand enabled), or both
1658 dummy widgets (expand disabled).
1659
1662 To get debug information from the parser, run rofi like:
1663 G_MESSAGES_DEBUG=Parser rofi -show run
1666 Syntax errors are shown in a popup and printed out to command line with
1670 the above command.
1671 To see the elements queried during running, run:
1674 G_MESSAGES_DEBUG=Theme rofi -show run
1677 To test minor changes, part of the theme can be passed on the command
1681 line, for example to set it to full-screen:
1682 rofi -theme-str 'window { fullscreen:true;}' -show run
1685 Another syntax to modify theme properties is:
1689 rofi -theme+window+fullscreen true -show run
1692 To print the current theme, run:
1696 rofi -dump-theme
1699
1703 Parts of the theme can be conditionally loaded, like the CSS @media op‐
1704 tion.
1705 @media ( min-width: 120 ) {
1708 }
1710 It supports the following keys as constraint:
1714 • min-width: load when width is bigger or equal then
1717 value.
1718 • max-width: load when width is smaller then value.
1720 • min-height: load when height is bigger or equal then
1722 value.
1723 • max-height: load when height is smaller then value.
1725 • min-aspect-ratio load when aspect ratio is over value.
1727 • max-aspect-ratio: load when aspect ratio is under value.
1729 • monitor-id: The monitor id, see rofi -help for id's.
1731 • enabled: Boolean option to enable. Supports environ‐
1733 ment variable.
1734 @media takes an integer number or a fraction, for integer number px can
1738 be added.
1739 @media ( min-width: 120 px ) {
1742 }
1744 @media ( enabled: env(DO_LIGHT, false ) {
1748 }
1750
1754 Rofi uses pango ⟨https://pango.gnome.org/⟩ for font rendering. The font
1755 should be specified in a format that pango understands. This normally
1756 is the font name followed by the font size. For example:
1757 mono 18
1760 Or
1764 FontAwesome 22
1767
1771 Rofi supports 3 ways of specifying an icon:
1772 • Filename
1775 • icon-name, this is looked up via the icon-theme.
1777 • Markup String. It renders a string as an icon.
1779 For the first two options, GdkPixbuf is used to open and render the
1783 icons. This in general gives support for most required image formats.
1784 For the string option it uses Pango to render the string. The string
1785 needs to start with a <span tag, that allows you to set color and font.
1786 Markup string:
1789 echo -en "testing\0icon\x1f<span color='red'>⏻</span>" | ./rofi -dmenu
1792 Getting supported icon formats:
1796 G_MESSAGES_DEBUG=Helpers.IconFetcher rofi
1799 This uses the debug framework and prints out a list of supported image
1803 file extensions.
1804
1807 The rasi file format offers two methods of including other files. This
1808 can be used to modify existing themes, or have multiple variations on a
1809 theme.
1810 • import: Import and parse a second file.
1813 • theme: Discard theme, and load file as a fresh theme.
1815 Syntax:
1819 @import "myfile"
1822 @theme "mytheme"
1823 The specified file can either by name, filename,full path.
1827 If a filename is provided, it will try to resolve it in the following
1830 order:
1831 • ${XDG_CONFIG_HOME}/rofi/themes/
1834 • ${XDG_CONFIG_HOME}/rofi/
1836 • ${XDG_DATA_HOME}/rofi/themes/
1838 • ${INSTALL PREFIX}/share/rofi/themes/
1840 A name is resolved as a filename by appending the .rasi extension.
1844
1847 Several examples are installed together with rofi. These can be found
1848 in {datadir}/rofi/themes/, where {datadir} is the install path of rofi
1849 data. When installed using a package manager, this is usually:
1850 /usr/share/.
1851
1854 rofi(1), rofi-script(5), rofi-theme-selector(1)
1855 rofi-theme ROFI-THEME(5)