1ROFI-THEME(5)                 File Formats Manual                ROFI-THEME(5)
2
3
4

NAME

6       rofi-theme - Rofi theme format files
7
8

GETTING STARTED WITH THEMING

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
114https://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

DEFAULT THEME LOADING

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

DESCRIPTION

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

FORMAT SPECIFICATION

Encoding

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

Comments

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

White space

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

File extension

259       The preferred file extension for the new theme format is rasi. This  is
260       an abbreviation for rofi advanced style information.
261
262

Basic Structure

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

Global properties section

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

Element theme section

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

Properties Format

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

String

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

Integer

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

Real

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

Boolean

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

Image

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

Color

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

Text style

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
639bold: make the text thicker then the surrounding text.
640
641italic: put the highlighted text in script type (slanted).
642
643underline: put a line under the text.
644
645strikethrough: put a line through the text.
646
647
648
649       The following options are available on pango 1.50.0 and up:
650
651
652uppercase: Uppercase the text.
653
654lowercase: 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
663capitalize: Capitalize the text.
664
665
666

Line style

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

Distance

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
693px: Screen pixels.
694
695em: Relative to text height.
696
697ch: Relative to width of a single number.
698
699mm: 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
743min   : Minimum of lvalue or rvalue;
744
745max   : Maximum of lvalue or rvalue;
746
747floor : Round down lvalue to the next multiple of rvalue
748
749ceil  : Round up lvalue to the next multiple of rvalue
750
751round : Round lvalue to the next multiple of rvalue
752
753
754
755       It uses the C precedence ordering.
756
757

Padding

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

Border

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

Position

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

Visibility

838       It is possible to hide widgets:
839
840
841              inputbar {
842                  enabled: false;
843              }
844
845
846

Reference

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

Orientation

898              • Format: (horizontal|vertical)
899
900
901
902       Specify the orientation of the widget.
903
904

Cursor

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

List of keywords

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

List of values

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

Environment variable

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

Inherit

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

ELEMENTS PATHS

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

SUPPORTED ELEMENT PATH

Name

1014       The current widgets available in rofi:
1015
1016
1017window
1018
1019overlay: the overlay widget.
1020
1021mainbox: The mainbox box.
1022
1023inputbar: The input bar box.
1024
1025box: the horizontal @box packing the widgets
1026
1027case-indicator: the case/sort indicator @textbox
1028
1029prompt: the prompt @textbox
1030
1031entry: the main entry @textbox
1032
1033num-rows: Shows the total number of rows.
1034
1035num-filtered-rows:  Shows  the  total number of rows after
1036                    filtering.
1037
1038textbox-current-entry: Shows the text of the currently se‐
1039                    lected entry.
1040
1041icon-current-entry:  Shows  the  icon of the currently se‐
1042                    lected entry.
1043
1044
1045
1046listview: The listview.
1047
1048scrollbar: the listview scrollbar
1049
1050element: a box in the listview holding the entries
1051
1052element-icon: the widget in the listview's entry showing
1053                      the (optional) icon
1054
1055element-index:  the  widget in the listview's entry key‐
1056                      bindable index (1,2,3..0)
1057
1058element-text: the widget in the listview's entry showing
1059                      the text.
1060
1061
1062
1063
1064
1065mode-switcher: the main horizontal @box packing the buttons.
1066
1067button: the buttons @textbox for each mode
1068
1069
1070
1071message: The container holding the textbox.
1072
1073textbox: 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

State

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

SUPPORTED PROPERTIES

1146       The following properties are currently supported:
1147
1148
1149   all widgets:
1150enabled:           enable/disable rendering of the widget
1151
1152padding:           padding Padding on the inside of the widget
1153
1154margin:            padding Margin on the outside of the widget
1155
1156border:            border Border around  the  widget  (between
1157                padding and margin)/
1158
1159border-radius:     padding Sets a radius on the corners of the
1160                borders.
1161
1162background-color:  color Background color
1163
1164background-image:  image Background image
1165
1166border-color:      color Color of the border
1167
1168cursor:            cursor Type of mouse  cursor  that  is  set
1169                when the mouse pointer is hovered over the widget.
1170
1171
1172
1173   window:
1174font:            string The font used in the window
1175
1176transparency:     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
1182location:        position The place of the anchor on the moni‐
1183                tor
1184
1185anchor:         anchor The anchor position on the window
1186
1187fullscreen:     boolean Window is fullscreen.
1188
1189width:          distance The width of the window
1190
1191x-offset:       distance
1192
1193y-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:
1199background-color:    color
1200
1201handle-width:        distance
1202
1203handle-color:        color
1204
1205border-color:        color
1206
1207
1208
1209   box:
1210orientation:      orientation
1211                    Set the direction the elements are packed.
1212
1213spacing:          distance
1214                    Distance between the packed elements.
1215
1216
1217
1218   textbox:
1219background-color:  color
1220
1221border-color:       the  color  used for the border around the
1222                widget.
1223
1224font:              the font used by this textbox (string).
1225
1226str/content:   the string to display by this textbox (string).
1227
1228vertical-align:    Vertical alignment of the  text.  A  number
1229                between 0 (top) and 1 (bottom).
1230
1231horizontal-align:   Horizontal alignment of the text. A number
1232                between 0 (left) and 1 (right).
1233
1234text-color:        the text color to use.
1235
1236text-transform:    text style {color} for the whole text.
1237
1238highlight:         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
1243width:             override the desired width for the textbox.
1244
1245content:           Set the displayed text (String).
1246
1247placeholder:        Set the displayed text (String) when noth‐
1248                ing is entered.
1249
1250placeholder-color: Color of the placeholder text.
1251
1252blink:             Enable/Disable blinking on an input textbox
1253                (Boolean).
1254
1255markup:             Force  markup  on,  beware that only valid
1256                pango markup strings are shown.
1257
1258tab-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:
1267columns:         integer Number of columns to show  (at  least
1268                1)
1269
1270fixed-height:    boolean Always show lines rows, even if fewer
1271                elements are available.
1272
1273dynamic:         boolean True if the size should  change  when
1274                filtering  the  list,  False  if  it  should keep the original
1275                height.
1276
1277scrollbar:        boolean  If  the  scrollbar  should  be  en‐
1278                abled/disabled.
1279
1280scrollbar-width: distance Width of the scrollbar
1281
1282cycle:            boolean  When  navigating,  it  should  wrap
1283                around
1284
1285spacing:         distance Spacing between the  elements  (both
1286                vertical and horizontal)
1287
1288lines:            integer  Number  of rows to show in the list
1289                view.
1290
1291layout:            orientation  Indicate  how   elements   are
1292                stacked. Horizontal implements the dmenu style.
1293
1294reverse:          boolean  Reverse  the  ordering (top down to
1295                bottom up).
1296
1297flow:           orientation The order the elements  are  layed
1298                out.  Vertical is the original 'column' view.
1299
1300fixed-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
1304require-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

Layout

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
1348http://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

DEBUGGING

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

Media support

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
1716min-width:          load  when  width  is bigger or equal then
1717                value.
1718
1719max-width:         load when width is smaller then value.
1720
1721min-height:        load when height is bigger  or  equal  then
1722                value.
1723
1724max-height:        load when height is smaller then value.
1725
1726min-aspect-ratio   load when aspect ratio is over value.
1727
1728max-aspect-ratio:  load when aspect ratio is under value.
1729
1730monitor-id:        The monitor id, see rofi -help for id's.
1731
1732enabled:           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

Font Parsing

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

Icon Handling

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

Multiple file handling

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

EXAMPLES

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

SEE ALSO

1854       rofi(1), rofi-script(5), rofi-theme-selector(1)
1855
1856
1857
1858                                  rofi-theme                     ROFI-THEME(5)
Impressum