1ROFI-THEME(5) File Formats Manual ROFI-THEME(5)
2
3
4
6 rofi-theme - Rofi theme format files
7
8
10 The easiest way to get started theming rofi is by modifying your exist‐
11 ing theme.
12
13
14 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
19
20 A basic config:
21
22
23 configuration {
24 modes: [ combi ];
25 combi-modes: [ window, drun, run ];
26 }
27
28 @theme "gruvbox-light"
29
30 /* Insert theme modifications after this */
31
32
33
34 For example if we want to change the Type to filter text in the entry
35 box we append the following:
36
37
38 entry {
39 placeholder: "Type here";
40 }
41
42
43
44 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
49
50 To change the mouse over cursor to a pointer, add:
51
52
53 entry {
54 placeholder: "Type here";
55 cursor: pointer;
56 }
57
58
59
60 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
64
65 element {
66 orientation: horizontal;
67 children: [ element-text, element-icon ];
68 spacing: 5px;
69 }
70
71
72
73
74 Resulting in the following packing:
75
76
77 ┌─────────────────────────────────────────────────────────────────────┐
78 │ element │
79 │ ┌─────────────────────────────────────────────┐ ┌─────────────────┐ │
80 │ │element─text │ │ element─icon │ │
81 │ └─────────────────────────────────────────────┘ └─────────────────┘ │
82 └─────────────────────────────────────────────────────────────────────┘
83
84
85
86 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
92
93 To increase the icon-size, we need to modify the element-icon widget.
94
95
96 element-icon {
97 size: 2.5em;
98 }
99
100
101
102 ┌─────────────────────────────────────────────────────────────────────┐
103 │ element │
104 │ ┌─────────────────────────────────────────────┐ ┌─────────────────┐ │
105 │ │element─text │ │ element │ │
106 │ │ │ │ ─ │ │
107 │ │ │ │ icon │ │
108 │ └─────────────────────────────────────────────┘ └─────────────────┘ │
109 └─────────────────────────────────────────────────────────────────────┘
110
111
112
113 In this example we specify the size in the em
114 ⟨https://www.w3.org/Style/LieBos3e/em⟩ unit.
115
116
117 Now lets change the text color of both the entry and the element-text
118 widget to red and background to blue.
119
120
121 entry, element-text {
122 text-color: red;
123 background-color: rgb(0,0,255);
124 }
125
126
127
128 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
133
134 If you want to center the text relative to the icon, we can set this:
135
136
137 element-text {
138 vertical-align: 0.5;
139 }
140
141
142
143 ┌─────────────────────────────────────────────────────────────────────┐
144 │ element │
145 │ ┌─────────────────────────────────────────────┐ ┌─────────────────┐ │
146 │ │ │ │ element │ │
147 │ │element-text │ │ ─ │ │
148 │ │ │ │ icon │ │
149 │ └─────────────────────────────────────────────┘ └─────────────────┘ │
150 └─────────────────────────────────────────────────────────────────────┘
151
152
153
154 If you want to see the complete theme, including the modification you
155 can run:
156
157
158 rofi -dump-theme
159
160
161
163 By default, rofi loads the default theme. This theme is always loaded.
164 The default configuration contains:
165
166
167 @theme "default"
168
169
170
171 To unload the default theme, and load another theme, add the @theme
172 statement to your config.rasi file.
173
174
175 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
179
180 For the difference between @import and @theme see the Multiple file
181 handling section in this manpage.
182
183
184 To see the default theme, run the following command:
185
186
187 rofi -no-config -dump-theme
188
189
190
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
200
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
206
208 C and C++ file comments are supported.
209
210
211 • Anything after // and before a newline is considered a com‐
212 ment.
213
214 • Everything between /* and */ is a comment, this comment can
215 span multiple lines.
216
217
218
219 Comments can be nested and the C comments can be inline.
220
221
222 The following is valid:
223
224
225 // Magic comment.
226 property: /* comment */ value;
227
228
229
230 However, this is not:
231
232
233 prop/*comment*/erty: value;
234
235
236
238 White space and newlines, like comments, are ignored by the parser.
239
240
241 This:
242
243
244 property: name;
245
246
247
248 Is identical to:
249
250
251 property :
252 name
253
254 ;
255
256
257
259 The preferred file extension for the new theme format is rasi. This is
260 an abbreviation for rofi advanced style information.
261
262
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
268
269 It is advised to define the global properties section on top of the
270 file to make inheritance of properties clearer.
271
272
273 /* Global properties section */
274 * {
275 // list of properties
276 }
277
278 /* Element theme section. */
279 {element path} {
280 // list of properties
281 }
282 {elements... } {
283 // list of properties
284 }
285
286
287
288 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
291
293 A theme can have one or more global properties sections. If there is
294 more than one, they will be merged.
295
296
297 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
301
302 A global properties section is indicated with a * as element path.
303
304
306 A theme can have multiple element theme sections.
307
308
309 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
314
315 This is a valid element name:
316
317
318 element normal.normal {
319 background-color: blue;
320 }
321 button {
322 background-color: blue;
323 }
324
325
326
327 And is identical to:
328
329
330 element normal normal, button {
331 background-color: blue;
332 }
333
334
335
336 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
340
341 window {
342 a: 1;
343 b: 2;
344 children: [ mainbox ];
345 }
346 mainbox {
347 a: inherit;
348 b: 4;
349 c: 8;
350 }
351
352
353
354 The element mainbox will have the following set of properties (if main‐
355 box is a child of window):
356
357
358 a: 1;
359 b: 4;
360 c: 8;
361
362
363
364 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
368
370 The properties in a section consist of:
371
372
373 {identifier}: {value};
374
375
376
377 Both fields are mandatory for a property.
378
379
380 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
387
388 The current theme format supports different types:
389
390
391 • a string
392
393 • an integer number
394
395 • a fractional number
396
397 • a boolean value
398
399 • a color
400
401 • image
402
403 • text style
404
405 • line style
406
407 • a distance
408
409 • a padding
410
411 • a border
412
413 • a position
414
415 • a reference
416
417 • an orientation
418
419 • a cursor
420
421 • a list of keywords
422
423 • an array of values
424
425 • an environment variable
426
427 • Inherit
428
429
430
431 Some of these types are a combination of other types.
432
433
435 • Format: "[:print:]+"
436
437
438
439 A string is always surrounded by double quotes ("). Between the quotes
440 there can be any printable character.
441
442
443 For example:
444
445
446 font: "Awasome 12";
447
448
449
450 The string must be valid UTF-8, special characters can be escaped:
451
452
453 text {
454 content: "Line one\n\tIndented line two";
455 }
456
457
458
459 The following special characters can be escaped: \b, \f, \n, \r, \t,
460 \v, \ and ".
461
462
464 • Format: [-+]?[:digit:]+
465
466
467
468 An integer may contain any number.
469
470
471 For examples:
472
473
474 lines: 12;
475
476
477
479 • Format: [-+]?[:digit:]+(\.[:digit:]+)?
480
481
482
483 A real is an integer with an optional fraction.
484
485
486 For example:
487
488
489 real: 3.4;
490
491
492
493 The following is not valid: .3, 3. or scientific notation: 3.4e-3.
494
495
497 • Format: (true|false)
498
499
500
501 Boolean value is either true or false. This is case-sensitive.
502
503
504 For example:
505
506
507 dynamic: false;
508
509
510
512 rofi support a limited set of background-image formats.
513
514
515 • Format: url("path to image");
516
517 • Format: url("path to image", scale); where scale is: none,
518 both, width, height
519
520 • Format: linear-gradient(stop color,stop1, color, stop2 color,
521 ...);
522
523 • Format: linear-gradient(to direction, stop color,stop1, color,
524 stop2 color, ...); where direction is: top,left,right,bot‐
525 tom.
526
527 • Format: linear-gradient(angle, stop color,stop1, color, stop2
528 color, ...); Angle in deg,rad,grad (as used in color).
529
530
531
532 Where the path is a string, and stop color is of type color.
533
534
536 rofi supports the color formats as specified in the CSS standard (1,2,3
537 and some of CSS 4)
538
539
540 • Format: #{HEX}{3} (rgb)
541
542 • Format: #{HEX}{4} (rgba)
543
544 • Format: #{HEX}{6} (rrggbb)
545
546 • Format: #{HEX}{8} (rrggbbaa)
547
548 • Format: rgb[a]({INTEGER},{INTEGER},{INTEGER}[, {PERCENTAGE}])
549
550 • Format: rgb[a]({INTEGER}%,{INTEGER}%,{INTEGER}%[, {PERCENT‐
551 AGE}])
552
553 • Format: hsl[a]( {ANGLE}, {PERCENTAGE}, {PERCENTAGE} [, {PER‐
554 CENTAGE}])
555
556 • Format: hwb[a]( {ANGLE}, {PERCENTAGE}, {PERCENTAGE} [, {PER‐
557 CENTAGE}])
558
559 • Format: cmyk( {PERCENTAGE}, {PERCENTAGE}, {PERCENTAGE}, {PER‐
560 CENTAGE} [, {PERCENTAGE} ])
561
562 • Format: {named-color} [ / {PERCENTAGE} ]
563
564
565
566 The white-space format proposed in CSS4 is also supported.
567
568
569 The different values are:
570
571
572 • {HEX} is a hexadecimal number ('0-9a-f' case insensitive).
573
574 • {INTEGER} value can be between 0 and 255 or 0-100 when repre‐
575 senting percentage.
576
577 • {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
580 • {PERCENTAGE} can be between 0-1.0, or 0%-100%
581
582 • {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
611
612
613 For example:
614
615
616 background-color: #FF0000;
617 border-color: rgba(0,0,1, 0.5);
618 text-color: SeaGreen;
619
620
621
622 or
623
624
625 background-color: transparent;
626 text-color: Black;
627
628
629
631 • Format: (bold|italic|underline|strikethrough|none)
632
633
634
635 Text style indicates how the highlighted text is emphasized. None indi‐
636 cates that no emphasis should be applied.
637
638
639 • bold: make the text thicker then the surrounding text.
640
641 • italic: put the highlighted text in script type (slanted).
642
643 • underline: put a line under the text.
644
645 • strikethrough: put a line through the text.
646
647
648
649 The following options are available on pango 1.50.0 and up:
650
651
652 • uppercase: Uppercase the text.
653
654 • lowercase: Lowercase the text.
655
656
657
658 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
662
663 • capitalize: Capitalize the text.
664
665
666
668 • Format: (dash|solid)
669
670
671
672 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
676
678 • Format: {Integer}px
679
680 • Format: {Real}em
681
682 • Format: {Real}ch
683
684 • Format: {Real}%
685
686 • Format: {Integer}mm
687
688
689
690 A distance can be specified in 3 different units:
691
692
693 • px: Screen pixels.
694
695 • em: Relative to text height.
696
697 • ch: Relative to width of a single number.
698
699 • mm: Actual size in millimeters (based on dpi).
700
701 • %: Percentage of the monitor size.
702
703
704
705 Distances used in the horizontal direction use the monitor width. Dis‐
706 tances in the vertical direction use the monitor height. For example:
707
708
709 padding: 10%;
710
711
712
713 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
716
717 Calculating sizes
718 Rofi supports some maths in calculating sizes. For this it uses the CSS
719 syntax:
720
721
722 width: calc( 100% - 37px );
723
724
725
726 width: calc( 20% min 512 );
727
728
729
730 It supports the following operations:
731
732
733 • + : Add
734
735 • - : Subtract
736
737 • / : Divide
738
739 • * : Multiply
740
741 • % : Modulo
742
743 • min : Minimum of lvalue or rvalue;
744
745 • max : Maximum of lvalue or rvalue;
746
747 • floor : Round down lvalue to the next multiple of rvalue
748
749 • ceil : Round up lvalue to the next multiple of rvalue
750
751 • round : Round lvalue to the next multiple of rvalue
752
753
754
755 It uses the C precedence ordering.
756
757
759 • Format: {Integer}
760
761 • Format: {Distance}
762
763 • Format: {Distance} {Distance}
764
765 • Format: {Distance} {Distance} {Distance}
766
767 • Format: {Distance} {Distance} {Distance} {Distance}
768
769
770
771 If no unit is specified, pixels are assumed.
772
773
774 The different number of fields in the formats are parsed like:
775
776
777 • 1 field: all
778
779 • 2 fields: top&bottom left&right
780
781 • 3 fields: top, left&right, bottom
782
783 • 4 fields: top, right, bottom, left
784
785
786
788 • Format: {Integer}
789
790 • Format: {Distance}
791
792 • Format: {Distance} {Distance}
793
794 • Format: {Distance} {Distance} {Distance}
795
796 • Format: {Distance} {Distance} {Distance} {Distance}
797
798 • Format: {Distance} {Line style}
799
800 • Format: {Distance} {Line style} {Distance} {Line style}
801
802 • Format: {Distance} {Line style} {Distance} {Line style} {Dis‐
803 tance} {Line style}
804
805 • Format: {Distance} {Line style} {Distance} {Line style} {Dis‐
806 tance} {Line style} {Distance} {Line style}
807
808
809
810 Borders are identical to padding, except that each distance field has a
811 line style property.
812
813
814 When no unit is specified, pixels are assumed.
815
816
817
819 Indicate a place on the window/monitor.
820
821
822 ┌─────────────┬─────────────┬─────────────┐
823 │ north west │ north │ north east │
824 ├─────────────┼─────────────┼─────────────┤
825 │ west │ center │ east │
826 ├─────────────┼─────────────┼─────────────┤
827 │ south west │ south │ south east │
828 └─────────────┴─────────────┴─────────────┘
829
830
831
832 • Format: (center|east|north|west|south|north east|north
833 west|south west|south east)
834
835
836
838 It is possible to hide widgets:
839
840
841 inputbar {
842 enabled: false;
843 }
844
845
846
848 • Format: @{PROPERTY NAME}
849
850
851
852 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
857
858 highlight: bold @pink;
859
860
861
862 But this is:
863
864
865 * {
866 myhigh: bold #FAA;
867 }
868
869 window {
870 highlight: @myhigh;
871 }
872
873
874
875 • Format: var(PROPERTY NAME, DEFAULT)
876
877
878
879 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
883
884 Example:
885
886
887 window {
888 width: var( width, 30%);
889 }
890
891
892
893 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
896
898 • Format: (horizontal|vertical)
899
900
901
902 Specify the orientation of the widget.
903
904
906 • Format: (default|pointer|text)
907
908
909
910 Specify the type of mouse cursor that is set when the mouse pointer is
911 over the widget.
912
913
915 • Format: [ keyword, keyword ]
916
917
918
919 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
922
924 • Format: [ value, value, ... ]
925
926
927
928 An list starts with a '[' and ends with a ']'. The entries in the list
929 are comma-separated.
930
931
933 • Format: ${:alnum:}
934
935
936
937 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
941
942 * {
943 background-color: ${BG};
944 }
945
946
947
948 • Format: env(ENVIRONMENT, default)
949
950
951
952 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
957
958 window {
959 width: env(WIDTH, 40%);
960 }
961
962
963
964 If environment WIDTH is set, then that value is parsed, otherwise the
965 default value (40%).
966
967
969 • Format: inherit
970
971
972
973 Inherits the property from its parent widget.
974
975
976 mainbox {
977 border-color: inherit;
978 }
979
980
981
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
986
987 For example:
988
989
990 element selected {
991 }
992
993
994
995 Here element selected is the name of the widget, selected is the state
996 of the widget.
997
998
999 The difference between dots and spaces is purely cosmetic. These are
1000 all the same:
1001
1002
1003 element .selected {
1004
1005 element.selected {
1006 }
1007 element selected {
1008 }
1009
1010
1011
1014 The current widgets available in rofi:
1015
1016
1017 • window
1018
1019 • overlay: the overlay widget.
1020
1021 • mainbox: The mainbox box.
1022
1023 • inputbar: The input bar box.
1024
1025 • box: the horizontal @box packing the widgets
1026
1027 • case-indicator: the case/sort indicator @textbox
1028
1029 • prompt: the prompt @textbox
1030
1031 • entry: the main entry @textbox
1032
1033 • num-rows: Shows the total number of rows.
1034
1035 • num-filtered-rows: Shows the total number of rows after
1036 filtering.
1037
1038 • textbox-current-entry: Shows the text of the currently se‐
1039 lected entry.
1040
1041 • icon-current-entry: Shows the icon of the currently se‐
1042 lected entry.
1043
1044
1045
1046 • listview: The listview.
1047
1048 • scrollbar: the listview scrollbar
1049
1050 • element: a box in the listview holding the entries
1051
1052 • element-icon: the widget in the listview's entry showing
1053 the (optional) icon
1054
1055 • element-index: the widget in the listview's entry key‐
1056 bindable index (1,2,3..0)
1057
1058 • element-text: the widget in the listview's entry showing
1059 the text.
1060
1061
1062
1063
1064
1065 • mode-switcher: the main horizontal @box packing the buttons.
1066
1067 • button: the buttons @textbox for each mode
1068
1069
1070
1071 • message: The container holding the textbox.
1072
1073 • textbox: the message textbox
1074
1075
1076
1077
1078
1079
1080
1081 Note that these path names match the default theme. Themes that provide
1082 a custom layout will have different elements, and structure.
1083
1084
1086 State: State of widget
1087
1088
1089 Optional flag(s) indicating state of the widget, used for theming.
1090
1091
1092 These are appended after the name or class of the widget.
1093
1094
1095 Example:
1096 button selected.normal { }
1097
1098
1099 element selected.urgent { }
1100
1101
1102 Currently only the entrybox and scrollbar have states:
1103
1104
1105 Entrybox:
1106 {visible modifier}.{state}
1107
1108
1109 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
1114
1115 Where state is:
1116 * normal: no modification
1117 * urgent: this entry is marked urgent
1118 * active: this entry is marked active
1119
1120
1121 These can be mixed.
1122
1123
1124 Example:
1125
1126
1127 nametotextbox selected.active {
1128 background-color: #003642;
1129 text-color: #008ed4;
1130 }
1131
1132
1133
1134 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
1138
1139 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
1144
1146 The following properties are currently supported:
1147
1148
1149 all widgets:
1150 • enabled: enable/disable rendering of the widget
1151
1152 • padding: padding Padding on the inside of the widget
1153
1154 • margin: padding Margin on the outside of the widget
1155
1156 • border: border Border around the widget (between
1157 padding and margin)/
1158
1159 • border-radius: padding Sets a radius on the corners of the
1160 borders.
1161
1162 • background-color: color Background color
1163
1164 • background-image: image Background image
1165
1166 • border-color: color Color of the border
1167
1168 • cursor: cursor Type of mouse cursor that is set
1169 when the mouse pointer is hovered over the widget.
1170
1171
1172
1173 window:
1174 • font: string The font used in the window
1175
1176 • 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
1182 • location: position The place of the anchor on the moni‐
1183 tor
1184
1185 • anchor: anchor The anchor position on the window
1186
1187 • fullscreen: boolean Window is fullscreen.
1188
1189 • width: distance The width of the window
1190
1191 • x-offset: distance
1192
1193 • 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
1196
1197
1198 scrollbar:
1199 • background-color: color
1200
1201 • handle-width: distance
1202
1203 • handle-color: color
1204
1205 • border-color: color
1206
1207
1208
1209 box:
1210 • orientation: orientation
1211 Set the direction the elements are packed.
1212
1213 • spacing: distance
1214 Distance between the packed elements.
1215
1216
1217
1218 textbox:
1219 • background-color: color
1220
1221 • border-color: the color used for the border around the
1222 widget.
1223
1224 • font: the font used by this textbox (string).
1225
1226 • str/content: the string to display by this textbox (string).
1227
1228 • vertical-align: Vertical alignment of the text. A number
1229 between 0 (top) and 1 (bottom).
1230
1231 • horizontal-align: Horizontal alignment of the text. A number
1232 between 0 (left) and 1 (right).
1233
1234 • text-color: the text color to use.
1235
1236 • text-transform: text style {color} for the whole text.
1237
1238 • 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
1243 • width: override the desired width for the textbox.
1244
1245 • content: Set the displayed text (String).
1246
1247 • placeholder: Set the displayed text (String) when noth‐
1248 ing is entered.
1249
1250 • placeholder-color: Color of the placeholder text.
1251
1252 • blink: Enable/Disable blinking on an input textbox
1253 (Boolean).
1254
1255 • markup: Force markup on, beware that only valid
1256 pango markup strings are shown.
1257
1258 • 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
1264
1265
1266 listview:
1267 • columns: integer Number of columns to show (at least
1268 1)
1269
1270 • fixed-height: boolean Always show lines rows, even if fewer
1271 elements are available.
1272
1273 • dynamic: boolean True if the size should change when
1274 filtering the list, False if it should keep the original
1275 height.
1276
1277 • scrollbar: boolean If the scrollbar should be en‐
1278 abled/disabled.
1279
1280 • scrollbar-width: distance Width of the scrollbar
1281
1282 • cycle: boolean When navigating, it should wrap
1283 around
1284
1285 • spacing: distance Spacing between the elements (both
1286 vertical and horizontal)
1287
1288 • lines: integer Number of rows to show in the list
1289 view.
1290
1291 • layout: orientation Indicate how elements are
1292 stacked. Horizontal implements the dmenu style.
1293
1294 • reverse: boolean Reverse the ordering (top down to
1295 bottom up).
1296
1297 • flow: orientation The order the elements are layed
1298 out. Vertical is the original 'column' view.
1299
1300 • 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
1304 • require-input: boolean Listview requires user input to show
1305 up.
1306
1307
1308
1309 Each element is a box called element. Each element can contain an ele‐
1310 ment-icon and element-text.
1311
1312
1313 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
1319
1320 To disable highlighting:
1321
1322
1323 element-text {
1324 highlight: None;
1325 }
1326
1327
1328
1329 To set to red underlined:
1330
1331
1332 element-text {
1333 highlight: underline red;
1334 }
1335
1336
1337
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
1344
1345 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
1350
1351 The current layout of rofi is structured as follows:
1352
1353
1354 ┌────────────────────────────────────────────────────────────────────────────────────┐
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
1391
1392
1393
1394
1395 • ci is the case-indicator
1396
1397 • fr is the num-filtered-rows
1398
1399 • ns is the num-rows
1400
1401
1402
1403
1404 Error message structure
1405 ┌──────────────────────────────────────────────────────────────────────────────────┐
1406 │ window {BOX:vertical} │
1407 │ ┌─────────────────────────────────────────────────────────────────────────────┐ │
1408 │ │ error─message {BOX:vertical} │ │
1409 │ │ ┌────────────────────────────────────────────────────────────────────────┐ │ │
1410 │ │ │ textbox │ │ │
1411 │ │ └────────────────────────────────────────────────────────────────────────┘ │ │
1412 │ └─────────────────────────────────────────────────────────────────────────────┘ │
1413 └──────────────────────────────────────────────────────────────────────────────────┘
1414
1415
1416
1417
1418 Advanced layout
1419 The layout of rofi can be tweaked by packing the 'fixed' widgets in a
1420 custom structure.
1421
1422
1423 The following widgets are fixed, as they provide core rofi functional‐
1424 ity:
1425
1426
1427 • prompt
1428
1429 • entry
1430
1431 • overlay
1432
1433 • case-indicator
1434
1435 • message
1436
1437 • listview
1438
1439 • mode-switcher
1440
1441 • num-rows
1442
1443 • num-filtered-rows
1444
1445
1446
1447 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
1451
1452 • mainbox Packs: inputbar, message, listview, mode-switcher
1453
1454 • inputbar Packs: prompt,entry,case-indicator
1455
1456
1457
1458 Any widget name starting with textbox is a textbox widget, others are
1459 box widgets and can pack other widgets.
1460
1461
1462 There are several special widgets that can be used by prefixing the
1463 name of the widget:
1464
1465
1466 textbox
1467 This is a read-only textbox widget. The displayed string can be set
1468 with content.
1469
1470
1471 Example:
1472
1473
1474 textbox-custom {
1475 expand: false;
1476 content: "My Message";
1477 }
1478
1479
1480
1481 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
1487
1488 If the squared property is set to false the widget height and width are
1489 not forced to be equal.
1490
1491
1492 Example:
1493
1494
1495 icon-paste {
1496 expand: false;
1497 filename: "gtk-paste";
1498 size: 24;
1499 vertical-align: 0.5;
1500 action: "kb-primary-paste";
1501 }
1502
1503
1504
1505 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
1510
1511 button-paste {
1512 expand: false;
1513 content: "My Clickable Message";
1514 vertical-align: 0.5;
1515 action: "kb-primary-paste";
1516 }
1517
1518
1519
1520 Children
1521 To specify children, set the children property (this always happens on
1522 the box child, see example below):
1523
1524
1525 inputbar {
1526 children: [prompt,entry,overlay,case-indicator];
1527 }
1528
1529
1530
1531 The theme needs to be updated to match the hierarchy specified.
1532
1533
1534 Below is an example of a theme emulating dmenu:
1535
1536
1537 * {
1538 background-color: Black;
1539 text-color: White;
1540 border-color: White;
1541 font: "Times New Roman 12";
1542 }
1543
1544 window {
1545 anchor: north;
1546 location: north;
1547 width: 100%;
1548 padding: 4px;
1549 children: [ horibox ];
1550 }
1551
1552 horibox {
1553 orientation: horizontal;
1554 children: [ prompt, entry, listview ];
1555 }
1556
1557 listview {
1558 layout: horizontal;
1559 spacing: 5px;
1560 lines: 10;
1561 }
1562
1563 entry {
1564 expand: false;
1565 width: 10em;
1566 }
1567
1568 element {
1569 padding: 0px 2px;
1570 }
1571 element selected {
1572 background-color: SteelBlue;
1573 }
1574
1575
1576
1577 Padding and margin
1578 Just like CSS, rofi uses the box model for each widget.
1579
1580
1581 ┌──────────────────────────────────────────────────────────────────┐
1582 │ margin │
1583 │ ┌────────────────────────────────────────────────────────────┐ │
1584 │ │ border │ │
1585 │ │ ┌────────────────────────────────────────────────────────┐ │ │
1586 │ │ │ padding │ │ │
1587 │ │ │ ┌────────────────────────────────────────────────────┐ │ │ │
1588 │ │ │ │ content │ │ │ │
1589 │ │ │ └────────────────────────────────────────────────────┘ │ │ │
1590 │ │ └────────────────────────────────────────────────────────┘ │ │
1591 │ └────────────────────────────────────────────────────────────┘ │
1592 └──────────────────────────────────────────────────────────────────┘
1593
1594
1595
1596 Explanation of the different parts:
1597
1598
1599 • Content - The content of the widget.
1600
1601 • Padding - Clears an area around the widget. The padding shows
1602 the background color of the widget.
1603
1604 • Border - A border that goes around the padding and content.
1605 The border use the border-color of the widget.
1606
1607 • Margin - Clears an area outside the border. The margin is
1608 transparent.
1609
1610
1611
1612 The box model allows us to add a border around elements, and to define
1613 space between elements.
1614
1615
1616 The size of each margin, border, and padding can be set. For the bor‐
1617 der, a linestyle and radius can be set.
1618
1619
1620 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
1625
1626 ┌───────────────────────────────────────┐
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
1636
1637
1638 Advanced box packing
1639 More dynamic spacing can be achieved by adding dummy widgets, for exam‐
1640 ple to make one widget centered:
1641
1642
1643 ┌────────────────────────────────────────────────────┐
1644 │ ┌───────────────┐ ┌────────┐ ┌───────────────┐ │
1645 │ │ dummy │ │ child │ │ dummy │ │
1646 │ │ expand: true; │ │ │ │ expand: true; │ │
1647 │ │ │ │ │ │ │ │
1648 │ │ │ │ │ │ │ │
1649 │ │ │ │ │ │ │ │
1650 │ └───────────────┘ └────────┘ └───────────────┘ │
1651 └────────────────────────────────────────────────────┘
1652
1653
1654
1655 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
1660
1662 To get debug information from the parser, run rofi like:
1663
1664
1665 G_MESSAGES_DEBUG=Parser rofi -show run
1666
1667
1668
1669 Syntax errors are shown in a popup and printed out to command line with
1670 the above command.
1671
1672
1673 To see the elements queried during running, run:
1674
1675
1676 G_MESSAGES_DEBUG=Theme rofi -show run
1677
1678
1679
1680 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
1683
1684 rofi -theme-str 'window { fullscreen:true;}' -show run
1685
1686
1687
1688 Another syntax to modify theme properties is:
1689
1690
1691 rofi -theme+window+fullscreen true -show run
1692
1693
1694
1695 To print the current theme, run:
1696
1697
1698 rofi -dump-theme
1699
1700
1701
1703 Parts of the theme can be conditionally loaded, like the CSS @media op‐
1704 tion.
1705
1706
1707 @media ( min-width: 120 ) {
1708
1709 }
1710
1711
1712
1713 It supports the following keys as constraint:
1714
1715
1716 • min-width: load when width is bigger or equal then
1717 value.
1718
1719 • max-width: load when width is smaller then value.
1720
1721 • min-height: load when height is bigger or equal then
1722 value.
1723
1724 • max-height: load when height is smaller then value.
1725
1726 • min-aspect-ratio load when aspect ratio is over value.
1727
1728 • max-aspect-ratio: load when aspect ratio is under value.
1729
1730 • monitor-id: The monitor id, see rofi -help for id's.
1731
1732 • enabled: Boolean option to enable. Supports environ‐
1733 ment variable.
1734
1735
1736
1737 @media takes an integer number or a fraction, for integer number px can
1738 be added.
1739
1740
1741 @media ( min-width: 120 px ) {
1742
1743 }
1744
1745
1746
1747 @media ( enabled: env(DO_LIGHT, false ) {
1748
1749 }
1750
1751
1752
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
1758
1759 mono 18
1760
1761
1762
1763 Or
1764
1765
1766 FontAwesome 22
1767
1768
1769
1771 Rofi supports 3 ways of specifying an icon:
1772
1773
1774 • Filename
1775
1776 • icon-name, this is looked up via the icon-theme.
1777
1778 • Markup String. It renders a string as an icon.
1779
1780
1781
1782 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
1787
1788 Markup string:
1789
1790
1791 echo -en "testing\0icon\x1f<span color='red'>⏻</span>" | ./rofi -dmenu
1792
1793
1794
1795 Getting supported icon formats:
1796
1797
1798 G_MESSAGES_DEBUG=Helpers.IconFetcher rofi
1799
1800
1801
1802 This uses the debug framework and prints out a list of supported image
1803 file extensions.
1804
1805
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
1811
1812 • import: Import and parse a second file.
1813
1814 • theme: Discard theme, and load file as a fresh theme.
1815
1816
1817
1818 Syntax:
1819
1820
1821 @import "myfile"
1822 @theme "mytheme"
1823
1824
1825
1826 The specified file can either by name, filename,full path.
1827
1828
1829 If a filename is provided, it will try to resolve it in the following
1830 order:
1831
1832
1833 • ${XDG_CONFIG_HOME}/rofi/themes/
1834
1835 • ${XDG_CONFIG_HOME}/rofi/
1836
1837 • ${XDG_DATA_HOME}/rofi/themes/
1838
1839 • ${INSTALL PREFIX}/share/rofi/themes/
1840
1841
1842
1843 A name is resolved as a filename by appending the .rasi extension.
1844
1845
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
1852
1854 rofi(1), rofi-script(5), rofi-theme-selector(1)
1855
1856
1857
1858 rofi-theme ROFI-THEME(5)