1ROFI-THEME(5) ROFI-THEME(5)
2
6 rofi-theme - Rofi theme format files
7
9 The need for a new theme format was motivated by the fact that the way
10 rofi handled widgets has changed. From a very static drawing of lines
11 and text to a nice structured form of packing widgets. This change made
12 it possible to provide a more flexible theme framework. The old theme
13 format and config file are not flexible enough to expose these options
14 in a user-friendly way. Therefor, a new file format has been created,
15 replacing the old one.
16
19 The encoding of the file is utf-8. Both unix (\n) and windows (\r\n)
20 newlines format are supported. But unix is preferred.
21
23 C and C++ file comments are supported.
24 · Anything after // and before a newline is considered a comment.
26 · Everything between /* and */ is a comment.
28 Comments can be nested and the C comments can be inline.
32 The following is valid:
34 // Magic comment.
38 property: /* comment */ value;
39 However, this is not:
43 prop/*comment*/erty: value;
47
51 White space and newlines, like comments, are ignored by the parser.
52 This:
54 property: name;
58 Is identical to:
62 property :
66 name
67 ;
69
73 The preferred file extension for the new theme format is rasi. This is
74 an abbreviation for rofi advanced style information.
75
77 Each element has a section with defined properties. Global properties
78 can be defined in section * { }. Sub-section names begin with a hash
79 symbol #.
80 It is advised to define the global properties section on top of the
82 file to make inheritance of properties clearer.
83 /* Global properties section */
87 * {
88 // list of properties
89 }
90 /* Element theme section. */
92 {element path} {
93 // list of properties
94 }
95 {elements... } {
96 // list of properties
97 }
98 If there are multiple sections with the same name, they are merged.
102 Duplicate properties are overwritten and the last parsed entry kept.
103
105 A theme can have one or more global properties sections. If there is
106 more than one, they will be merged.
107 The global properties section denotes the defaults for each element.
109 Each property of this section can be referenced with @{identifier} (See
110 Properties section)
111 A global properties section is indicated with a * as element path.
113
115 A theme can have multiple element theme sections.
116 The element path can consist of multiple names separated by whitespace
118 or dots. Each element may contain any number of letters, numbers and
119 -´s. The first element in the element path should always start with a
120 #. Multiple elements can be specified by a ,.
121 This is a valid element name:
123 element normal.normal {
127 background-color: blue;
128 }
129 button {
130 background-color: blue;
131 }
132 And is identical to:
136 element normal normal, button {
140 background-color: blue;
141 }
142 Each section inherits the global properties. Properties can be explic‐
146 itly inherited from their parent with the inherit keyword. In the fol‐
147 lowing example:
148 window {
152 a: 1;
153 b: 2;
154 }
155 mainbox {
156 a: inherit;
157 b: 4;
158 c: 8;
159 }
160 The element mainbox will have the following set of properties (if main‐
164 box is a child of window):
165 a: 1;
169 b: 4;
170 c: 8;
171 If multiple sections are defined with the same name, they are merged by
175 the parser. If multiple properties with the same name are defined in
176 one section, the last encountered property is used.
177
179 The properties in a section consist of:
180 {identifier}: {value};
184 Both fields are mandatory for a property.
188 The identifier names the specified property. Identifiers can consist of
190 any combination of numbers, letters and ´-´. It must not contain any
191 whitespace. The structure of the value defines the type of the prop‐
192 erty. The current parser does not define or enforce a certain type of a
193 particular identifier. When used, values with the wrong type that can‐
194 not be converted are ignored.
195 The current theme format supports different types:
197 · a string
199 · an integer number
201 · a fractional number
203 · a boolean value
205 · a color
207 · text style
209 · line style
211 · a distance
213 · a padding
215 · a border
217 · a position
219 · a reference
221 · an orientation
223 · a list of keywords
225 · an environment variable
227 · Inherit
229 Some of these types are a combination of other types.
233
235 · Format: "[:print:]+"
236 A string is always surrounded by double quotes ("). Between the quotes
240 there can be any printable character.
241 For example:
243 font: "Awasome 12";
247 The string must be valid UTF-8.
251
253 · Format: [-+]?[:digit:]+
254 An integer may contain any number.
258 For examples:
260 lines: 12;
264
268 · Format: [-+]?[:digit:]+(\.[:digit:]+)?
269 A real is an integer with an optional fraction.
273 For example:
275 real: 3.4;
279 The following is not valid: .3, 3. or scientific notation: 3.4e-3.
283
285 · Format: (true|false)
286 Boolean value is either true or false. This is case-sensitive.
290 For example:
292 dynamic: false;
296
300 rofi supports the color formats as specified in the CSS standard (1,2,3
301 and some of CSS 4)
302 · Format: #{HEX}{3} (rgb)
304 · Format: #{HEX}{4} (rgba)
306 · Format: #{HEX}{6} (rrggbb)
308 · Format: #{HEX}{8} (rrggbbaa)
310 · Format: rgb[a]({INTEGER},{INTEGER},{INTEGER}[, {PERCENTAGE}])
312 · Format: rgb[a]({INTEGER}%,{INTEGER}%,{INTEGER}%[, {PERCENTAGE}])
314 · Format: hsl[a]( {ANGLE}, {PERCENTAGE}, {PERCENTAGE} [, {PERCENT‐
316 AGE}])
317 · Format: hwb[a]( {ANGLE}, {PERCENTAGE}, {PERCENTAGE} [, {PERCENT‐
319 AGE}])
320 · Format: cmyk( {PERCENTAGE}, {PERCENTAGE}, {PERCENTAGE}, {PERCENT‐
322 AGE} [, {PERCENTAGE} ])
323 · Format: {named-color} [ / {PERCENTAGE} ]
325 The white-space format proposed in CSS4 is also supported.
329 The different values are:
331 · {HEX} is a hexadecimal number (´0-9a-f´ case insensitive).
333 · {INTEGER} value can be between 0 and 255 or 0-100 when representing
335 percentage.
336 · {ANGLE} is the angle on the color wheel, can be in deg, rad, grad
338 or turn. When no unit is specified, degrees is assumed.
339 · {PERCENTAGE} can be between 0-1.0, or 0%-100%
341 · {named-color} is one of the following colors:
343 AliceBlue, AntiqueWhite, Aqua, Aquamarine, Azure, Beige, Bisque,
345 Black, BlanchedAlmond, Blue, BlueViolet, Brown, BurlyWood, Cadet‐
346 Blue, Chartreuse, Chocolate, Coral, CornflowerBlue, Cornsilk, Crim‐
347 son, Cyan, DarkBlue, DarkCyan, DarkGoldenRod, DarkGray, DarkGrey,
348 DarkGreen, DarkKhaki, DarkMagenta, DarkOliveGreen, DarkOrange,
349 DarkOrchid, DarkRed, DarkSalmon, DarkSeaGreen, DarkSlateBlue, Dark‐
350 SlateGray, DarkSlateGrey, DarkTurquoise, DarkViolet, DeepPink,
351 DeepSkyBlue, DimGray, DimGrey, DodgerBlue, FireBrick, FloralWhite,
352 ForestGreen, Fuchsia, Gainsboro, GhostWhite, Gold, GoldenRod, Gray,
353 Grey, Green, GreenYellow, HoneyDew, HotPink, IndianRed, Indigo,
354 Ivory, Khaki, Lavender, LavenderBlush, LawnGreen, LemonChiffon,
355 LightBlue, LightCoral, LightCyan, LightGoldenRodYellow, LightGray,
356 LightGrey, LightGreen, LightPink, LightSalmon, LightSeaGreen,
357 LightSkyBlue, LightSlateGray, LightSlateGrey, LightSteelBlue,
358 LightYellow, Lime, LimeGreen, Linen, Magenta, Maroon, MediumAquaMa‐
359 rine, MediumBlue, MediumOrchid, MediumPurple, MediumSeaGreen, Medi‐
360 umSlateBlue, MediumSpringGreen, MediumTurquoise, MediumVioletRed,
361 MidnightBlue, MintCream, MistyRose, Moccasin, NavajoWhite, Navy,
362 OldLace, Olive, OliveDrab, Orange, OrangeRed, Orchid, PaleGolden‐
363 Rod, PaleGreen, PaleTurquoise, PaleVioletRed, PapayaWhip, Peach‐
364 Puff, Peru, Pink, Plum, PowderBlue, Purple, RebeccaPurple, Red,
365 RosyBrown, RoyalBlue, SaddleBrown, Salmon, SandyBrown, SeaGreen,
366 SeaShell, Sienna, Silver, SkyBlue, SlateBlue, SlateGray, SlateGrey,
367 Snow, SpringGreen, SteelBlue, Tan, Teal, Thistle, Tomato,
368 Turquoise, Violet, Wheat, White, WhiteSmoke, Yellow, Yellow‐
369 Green,transparent
370 For example:
374 background-color: #FF0000;
378 border-color: rgba(0,0,1, 0.5);
379 text-color: SeaGreen;
380 or
384 background-color: transparent;
388 text-color: Black;
389
393 · Format: (bold|italic|underline|strikethrough|none)
394 Text style indicates how the highlighted text is emphasized. None indi‐
398 cates that no emphasis should be applied.
399 · bold: make the text thicker then the surrounding text.
401 · italic: put the highlighted text in script type (slanted).
403 · underline: put a line under the highlighted text.
405 · strikethrough: put a line through the highlighted text.
407 · small caps: emphasise the text using capitalization.
409
413 · Format: (dash|solid)
414 Indicates how a line should be drawn. It currently supports: * dash: a
418 dashed line, where the gap is the same width as the dash * solid: a
419 solid line
420
422 · Format: {Integer}px
423 · Format: {Real}em
425 · Format: {Real}ch
427 · Format: {Real}%
429 A distance can be specified in 3 different units:
433 · px: Screen pixels.
435 · em: Relative to text height.
437 · ch: Relative to width of a single number.
439 · %: Percentage of the monitor size.
441 Distances used in the horizontal direction use the monitor width. Dis‐
445 tances in the vertical direction use the monitor height. For example:
446 padding: 10%;
450 On a full-HD (1920x1080) monitor, it defines a padding of 192 pixels on
454 the left and right side and 108 pixels on the top and bottom.
455
457 · Format: {Integer}
458 · Format: {Distance}
460 · Format: {Distance} {Distance}
462 · Format: {Distance} {Distance} {Distance}
464 · Format: {Distance} {Distance} {Distance} {Distance}
466 If no unit is specified, pixels are used.
470 The different number of fields in the formats are parsed like:
472 · 1 field: all
474 · 2 fields: top&bottom left&right
476 · 3 fields: top, left&right, bottom
478 · 4 fields: top, right, bottom, left
480
484 · Format: {Integer}
485 · Format: {Distance}
487 · Format: {Distance} {Distance}
489 · Format: {Distance} {Distance} {Distance}
491 · Format: {Distance} {Distance} {Distance} {Distance}
493 · Format: {Distance} {Line style}
495 · Format: {Distance} {Line style} {Distance} {Line style}
497 · Format: {Distance} {Line style} {Distance} {Line style} {Distance}
499 {Line style}
500 · Format: {Distance} {Line style} {Distance} {Line style} {Distance}
502 {Line style} {Distance} {Line style}
503 Borders are identical to padding, except that each distance field has a
507 line style property.
508
510 Indicate a place on the window/monitor.
511 · Format: (center|east|north|west|south|north east|north west|south
513 west|south east)
514 north west | north | north east
521 -------------|-------------|------------
522 west | center | east
523 -------------|-------------|------------
524 south west | south | south east
525
529 It is possible to hide widgets:
530 inputbar { enabled: false; }
532
534 · Format: @{PROPERTY NAME}
535 A reference can point to another reference. Currently, the maximum num‐
539 ber of redirects is 20. A property always refers to another property.
540 It cannot be used for a subpart of the property. For example, this is
541 not valid:
542 highlight: bold @pink;
546 But this is:
550 * {
554 myhigh: bold #FAA;
555 }
556 window {
558 highlight: @myhigh;
559 }
560
564 · Format: (horizontal|vertical)
565 Specify the orientation of the widget.
569
571 · Format: [ keyword, keyword ]
572 A list starts with a ´[´ and ends with a ´]´. The entries in the list
576 are comma-separated. The keyword in the list refers to an widget name.
577
579 · Format: ${:alnum:}
580 This will parse the environment variable as the property value. (that
584 then can be any of the above types). The environment variable should be
585 an alphanumeric string without white-space.
586 * {
590 background-color: ${BG};
591 }
592
596 · Format: inherit
597 Inherits the property from its parent widget.
601 mainbox {
605 border-color: inherit;
606 }
607
611 Element paths exists of two parts, the first part refers to the actual
612 widget by name. Some widgets have an extra state.
613 For example:
615 element selected {
619 }
620 Here element selected is the name of the widget, selected is the state
624 of the widget.
625 The difference between dots and spaces is purely cosmetic. These are
627 all the same:
628 element .selected {
632 element.selected {
634 }
635 element selected {
636 }
637
642 The current widgets available in rofi:
643 ·
645 · overlay: the overlay widget.
647 ·
649 ·
651 · box: the horizontal @box packing the widgets
653 · case-indicator: the case/sort indicator @textbox
655 · prompt: the prompt @textbox
657 · entry: the main entry @textbox
659 ·
664 · scrollbar: the listview scrollbar
666 · element: the entries in the listview
668 ·
673 · button: the buttons @textbox for each mode
675 ·
680 · textbox: the message textbox
682 Note that these path names match the default theme. Themes that provide
695 a custom layout will have different element paths.
696
698 State: State of widget
699 Optional flag(s) indicating state of the widget, used for theming.
701 These are appended after the name or class of the widget.
703 Example:
705 button selected.normal { }
706 element selected.urgent { }
708 Currently only the entrybox and scrollbar have states:
710 Entrybox:
712 {visible modifier}.{state}
713 Where visible modifier can be: * normal: no modification * selected:
715 the entry is selected/highlighted by user * alternate: the entry is at
716 an alternating row (uneven row)
717 Where state is: * normal: no modification * urgent: this entry is
719 marked urgent * active: this entry is marked active
720 These can be mixed.
722 Example:
724 nametotextbox selected.active {
728 background-color: #003642;
729 text-color: #008ed4;
730 }
731 Sets all selected textboxes marked active to the given text and back‐
735 ground color. Note that a state modifies the original element, it
736 therefore contains all the properties of that element.
737 Scrollbar
739 The scrollbar uses the handle state when drawing the small scrollbar
740 handle. This allows the colors used for drawing the handle to be set
741 independently.
742
744 The following properties are currently supported:
745 all widgets:
747 · padding: padding Padding on the inside of the widget
748 · margin: padding Margin on the outside of the widget
750 · border: border Border around the widget (between padding and mar‐
752 gin)/
753 · border-radius: padding Sets a radius on the corners of the borders.
755 · background-color: color Background color
757 · border-color: color Color of the border
759 · index: integer (This one does not inherit it value from the parent
761 widget)
762 window:
766 · font: string The font used in the window
767 · transparency: string Indicating if transparency should be used and
769 what type: real - True transparency. Only works with a compositor.
770 background - Take a screenshot of the background image and use
771 that. screenshot - Take a screenshot of the screen and use that.
772 Path to png file - Use an image.
773 · location: position The place of the anchor on the monitor
775 · anchor: anchor The anchor position on the window
777 · fullscreen: boolean Window is fullscreen.
779 · width: distance The width of the window
781 · x-offset: distance
783 · y-offset: distance The offset of the window to the anchor point,
785 allowing you to push the window left/right/up/down
786 scrollbar:
790 · background-color: color
791 · handle-width: distance
793 · handle-color: color
795 · border-color: color
797 box:
801 · orientation: orientation Set the direction the elements are packed.
802 · spacing: distance Distance between the packed elements.
804 textbox:
808 · background-color: color
809 · border-color: the color used for the border around the widget.
811 · font: the font used by this textbox (string)
813 · str: the string to display by this textbox (string)
815 · vertical-align: vertical alignment of the text (0 top, 1 bottom)
817 · horizontal-align: horizontal alignment of the text (0 left, 1
819 right)
820 · text-color: the text color to use
822 · highlight: text style {color} color is optional, multiple highlight
824 styles can be added like: bold underline italic #000000;
825 · width: override the desired width for the textbox
827 listview:
831 · columns: integer Number of columns to show (at least 1)
832 · fixed-height: boolean Always show lines rows, even if fewer ele‐
834 ments are available.
835 · dynamic: boolean True if the size should change when filtering the
837 list, False if it should keep the original height.
838 · scrollbar: boolean If the scrollbar should be enabled/disabled.
840 · scrollbar-width: distance Width of the scrollbar
842 · cycle: boolean When navigating, it should wrap around
844 · spacing: distance Spacing between the elements (both vertical and
846 horizontal)
847 · lines: integer Number of rows to show in the list view.
849 · layout: orientation Indicate how elements are stacked. Horizontal
851 implements the dmenu style.
852
856 The new format allows the layout of the rofi window to be tweaked
857 extensively. For each widget, the themer can specify padding, margin,
858 border, font, and more. It even allows, as an advanced feature, to pack
859 widgets in a custom structure.
860 Basic structure
862 The whole view is made out of boxes that pack other boxes or widgets.
863 The box can be vertical or horizontal. This is loosely inspired by GTK
864 http://gtk.org/.
865 The current layout of rofi is structured as follows:
867 |------------------------------------------------------------------------------------|
871 | window {BOX:vertical} |
872 | |-------------------------------------------------------------------------------| |
873 | | mainbox {BOX:vertical} | |
874 | | |---------------------------------------------------------------------------| | |
875 | | | inputbar {BOX:horizontal} | | |
876 | | | |---------| |-----------------------------------------------------| |---| | | |
877 | | | | prompt | | entry | |ci | | | |
878 | | | |---------| |-----------------------------------------------------| |---| | | |
879 | | |---------------------------------------------------------------------------| | |
880 | | | |
881 | | |---------------------------------------------------------------------------| | |
882 | | | message | | |
883 | | | |-----------------------------------------------------------------------| | | |
884 | | | | textbox | | | |
885 | | | |-----------------------------------------------------------------------| | | |
886 | | |---------------------------------------------------------------------------| | |
887 | | | |
888 | | |-----------------------------------------------------------------------------| |
889 | | | listview | |
890 | | |-----------------------------------------------------------------------------| |
891 | | | |
892 | | |---------------------------------------------------------------------------| | |
893 | | | mode-switcher {BOX:horizontal} | | |
894 | | | |---------------| |---------------| |--------------| |---------------| | | |
895 | | | | Button | | Button | | Button | | Button | | | |
896 | | | |---------------| |---------------| |--------------| |---------------| | | |
897 | | |---------------------------------------------------------------------------| | |
898 | |-------------------------------------------------------------------------------| |
899 |------------------------------------------------------------------------------------|
900 Error message structure
904 |-----------------------------------------------------------------------------------|
905 | window {BOX:vertical} |
906 | |------------------------------------------------------------------------------| |
907 | | error-message {BOX:vertical} | |
908 | | |-------------------------------------------------------------------------| | |
909 | | | textbox | | |
910 | | |-------------------------------------------------------------------------| | |
911 | |------------------------------------------------------------------------------| |
912 |-----------------------------------------------------------------------------------|
913 Advanced layout
915 The layout of rofi can be tweaked by packing the ´fixed´ widgets in a
916 custom structure.
917 The following widgets are fixed, as they provide core rofi functional‐
919 ity:
920 · prompt
922 · entry
924 · overlay
926 · case-indicator
928 · message
930 · listview
932 · mode-switcher
934 The following keywords are defined and can be used to automatically
938 pack a subset of the widgets. These are used in the default theme as
939 depicted in the figure above.
940 · mainbox Packs: inputbar, message, listview, mode-switcher
942 · inputbar Packs: prompt,entry,case-indicator
944 Any widget name starting with textbox is a textbox widget, others are
948 box widgets and can pack other widgets. To specify children, set the
949 children property (this always happens on the box child, see example
950 below):
951 children: [prompt,entry,overlay,case-indicator];
955 The theme needs to be updated to match the hierarchy specified.
959 Below is an example of a theme emulating dmenu:
961 * {
965 background-color: Black;
966 text-color: White;
967 border-color: White;
968 font: "Times New Roman 12";
969 }
970 window {
972 anchor: north;
973 location: north;
974 width: 100%;
975 padding: 4px;
976 children: [ horibox ];
977 }
978 horibox {
980 orientation: horizontal;
981 children: [ prompt, entry, listview ];
982 }
983 listview {
985 layout: horizontal;
986 spacing: 5px;
987 lines: 10;
988 }
989 entry {
991 expand: false;
992 width: 10em;
993 }
994 element {
996 padding: 0px 2px;
997 }
998 element selected {
999 background-color: SteelBlue;
1000 }
1001 Padding and margin
1005 Just like CSS, rofi uses the box model for each widget.
1006 |-------------------------------------------------------------------|
1010 | margin |
1011 | |-------------------------------------------------------------| |
1012 | | border | |
1013 | | |---------------------------------------------------------| | |
1014 | | | padding | | |
1015 | | | |-----------------------------------------------------| | | |
1016 | | | | content | | | |
1017 | | | |-----------------------------------------------------| | | |
1018 | | |---------------------------------------------------------| | |
1019 | |-------------------------------------------------------------| |
1020 |-------------------------------------------------------------------|
1021 Explanation of the different parts:
1025 · Content - The content of the widget.
1027 · Padding - Clears an area around the widget. The padding shows the
1029 background color of the widget.
1030 · Border - A border that goes around the padding and content. The
1032 border use the border-color of the widget.
1033 · Margin - Clears an area outside the border. The margin is transpar‐
1035 ent.
1036 The box model allows us to add a border around elements, and to define
1040 space between elements.
1041 The size of each margin, border, and padding can be set. For the bor‐
1043 der, a linestyle and radius can be set.
1044 Spacing
1046 Widgets that can pack more then one child widget (currently box and
1047 listview) have the spacing property. This property sets the distance
1048 between the packed widgets (both horizontally and vertically).
1049 |---------------------------------------|
1053 | |--------| s |--------| s |-------| |
1054 | | child | p | child | p | child | |
1055 | | | a | | a | | |
1056 | | | c | | c | | |
1057 | | | i | | i | | |
1058 | | | n | | n | | |
1059 | |--------| g |--------| g |-------| |
1060 |---------------------------------------|
1061 Advanced box packing
1065 More dynamic spacing can be achieved by adding dummy widgets, for exam‐
1066 ple to make one widget centered:
1067 |--------------------------------------------|
1071 | |-----------| |--------| |-----------| |
1072 | | dummy | | child | | dummy | |
1073 | | expand: y | | | | expand: y | |
1074 | | | | | | | |
1075 | | | | | | | |
1076 | | | | | | | |
1077 | |-----------| |--------| |-----------| |
1078 |--------------------------------------------|
1079 If both dummy widgets are set to expand, child will be centered.
1083 Depending on the expand flag of child the remaining space will be
1084 equally divided between both dummy and child widget (expand enabled),
1085 or both dummy widgets (expand disabled).
1086
1088 To get debug information from the parser, run rofi like:
1089 G_MESSAGES_DEBUG=Parser rofi -show run
1093 Syntax errors are shown in a popup and printed out to command line with
1097 the above command.
1098 To see the elements queried during running, run:
1100 G_MESSAGES_DEBUG=Theme rofi -show run
1104 To test minor changes, part of the theme can be passed on the command
1108 line, for example to set it to full-screen:
1109 rofi -theme-str ´#window { fullscreen:true;}´ -show run
1113 To print the current theme, run:
1117 rofi -dump-theme
1121
1125 Several examples are installed together with rofi. These can be found
1126 in {datadir}/rofi/themes/, where {datadir} is the install path of rofi
1127 data. When installed using a package manager, this is usually:
1128 /usr/share/.
1129
1131 rofi(1)
1132 May 2019 ROFI-THEME(5)