HIKARI(1)

📦 version 2.3.3, in fedora 43, fedora 44

HIKARI(1) — okay bestie, you've opened the manual page for hikari, and honestly? it's a whole vibe. it's hikari from the hikari - Wayland Compositor manual. let's get into it. 💖

✨ NAME ✨

hikari — Wayland Compositor. that's the whole name. iconic, brief, no notes. 💅

🌸 SYNTAX 🌸

hikari [-vh] [-a <executable>] [-c <config>]

💫 DESCRIPTION 💫

okay so. hikari is a stacking Wayland compositor that also has extra tiling capabilities, and it is heavily inspired by the Calm Window manager (cwm(1)). 🫶 its core concepts are views, workspaces, sheets and groups — those four are the whole personality, fr fr.

the following options are available:

  • -a <executable> — Specify autostart executable.
  • -c <config> — Specify a configuration file.
  • -h — Show this message and quit.
  • -v — Show version and quit.

🦋 CONCEPTS 🦋

🌈 View

Views are basically the windows of a Wayland client. ✨ each view belongs to at most one sheet and can also belong to at most one group. and a view can be in several states, which are:

  • hidden — Hidden views are not displayed on the workspace. Hiding a view removes this view from the workspace.
  • tiled — A tiled view is part of a layout. They can never be floating or invisible. periodt.
  • floating — Floating views can never become part of a layout. The floating state is indicated using a tilde in the sheet indicator.
  • invisible — When a view is set into invisible state it will not be displayed when switching to the containing sheet and stay hidden until it is explicitly requested to be shown. This can be used to keep long running views from cluttering the workspace. An invisible view can never be tiled and are indicated using square brackets in the sheet indicator.
  • maximized (horizontal, vertical and full) — Views with such a state can take up the entire horizontal and or vertical space of a workspace. Tiled views can also be maximized.
  • borrowed — Borrowing happens when a workspace contains a view that is not part of the current sheet. These views are called borrowed views and are indicated by the sheet indicator using the string x @ y, where x is the sheet the view is a member of and y is the sheet that is currently borrowing the view.
  • public — Public views are also displayed on the lock screen, in this case they will never accept input. The public state is indicated using an exclamation mark in the sheet indicator.
🚨 bestie listen: views that display sensible information should never be marked as public. do not do it. i'm not playing. 💀

🌸 Workspace

A workspace is the set of views that are currently visible. Unlike in most other Wayland compositors, hikari only has a single workspace for each output and we only manipulate its content using actions. While this seems like a superficial distinction it is important to keep in mind for some actions to make sense. 🧠 When switching to a sheet this sheet becomes the workspace sheet. On startup a workspace sheet is 1.

Views on a workspace are stacked from bottom to top, where the next view is higher up the stack and the previous view is one below. This order can be changed by raising or lowering views individually via actions. Selecting a view via cycling actions automatically raises this view to the top of the stacking order. ⭐

hikari provides multiple ways to cycle the views on a workspace. Cycling is a way to navigate to a view using key bindings. ⌨️

💜 Sheet

A sheet is a collection of views, each view can only be a member of a single sheet. Switching between sheets will replace the current content of the workspace with all the views that are a member of the selected sheet, this sheet will also become the current sheet. hikari has 9 general purpose sheets that correspond to the numbers 1 to 9 and a special purpose sheet 0. Views that are a member of sheet 0 will always be visible but stacked below the views of the selected sheet. A sheet that contains views is called inhabited.

When switching to a different sheet the current current sheet becomes the alternate sheet.

🎀 Group

Groups are a bit more fine grained than sheets. Like sheets, groups are a collection of views. Unlike sheets you can have a arbitrary number of groups and each group can have an arbitrary name. Views from one group can be spread among all available sheets. Some actions act on entire groups rather than individual views. 👑

✨ Layout

Each sheet can have at most one layout for tiling views. Applying a layout to a sheet introduces an additional ordering for views which is not altered by raising or lowering, which can be used to traverse the layout in the expected order. Each layout can be stored in one of the layout register a to z. 🔥

🦋 View indicators

View indicators show information about the current view as well as views belonging to the same group. They outline the border of the current view as well as all view borders belonging to the same group (obscured view borders will shine through the obscuring view). The focused view will also display so called indicator bars. Each bar holds some information, like title, sheet information, group and its mark (if one has been set for the view). ✨

🌈 Marks

Marks can be used to “speed dial” views, even if they are on a sheet other than the current sheet (note: such views will become borrowed in the process). Marks are represented by characters from a to z. When jumping to a mark the view will be brought forward and focused. If no view is bound to a mark the user can specify a command that is executed instead. This can be used to start an application that binds itself to this mark. 🚀

💅 Mode

hikari is a modal Wayland compositor and therefore offers several modes for actions like changing a views group, mark or sheet as well a jumping to marks or grabbing input events and layout selection. 🎛️

💖 CONFIGURATION 💖

hikari is configured using libucl(3) as a configuration file format. 📝 The configuration is located under $XDG_CONFIG_HOME/hikari/hikari.conf. If this file is not found hikari is going to try hikari.conf from the install etc directory.

The default configuration is going to use $TERMINAL as your standard terminal application.

On startup hikari attempts to execute ~/.config/hikari/autostart to autostart applications. 🏃‍♀️

🌱 Environment Variables

hikari supports the use of environment variables in its string values. Occurrences of ${VARIABLE} or $VARIABLE inside a string will be substituted with the value of an environment variable named VARIABLE. If no such environment variable exists, no substituation takes place. 🙈

You can use double dollar signs to escape variables: $${VARIABLE} will result in ${VARIABLE}, $$VARIABLE will result in $VARIABLE.

🔥 ACTIONS 🔥

⭐ General actions

  • lock — Lock hikari and turn off all outputs. To unlock you need to enter your password and press enter. Being able to unlock requires hikari-unlocker to be in the PATH and running with setuid(2) root privileges (those are required to check if the entered password is correct). hikari-unlocker also needs pam.conf(5) to be aware of its existence, therefore there must be a hikari-unlocker service file in pam.d.

The lock screen displays all views that are marked as public which allows applications to provide information to the user when the computer is locked (e.g. a clock). 🕐

  • quit — Issues a quit operation to all views, allowing them to prompt their shutdown dialog if they have any. Issuing this operation again during shutdown will terminate hikari right away. 😭
  • reload — Reload and apply the configuration. ♻️

👑 Group actions

  • group-cycle-[next|prev] — Cycle to the next or previous group according to the stacking order by cycling through the top most view of each group. The next view is further up the stack and the previous view is further down the stack. Reaching each end of the stack just wraps around. Once a view is selected it will be raised to the top of the stacking order. Selecting happens by releasing the modifier key. ⌨️
  • group-cycle-view-[next|prev|first|last] — Cycle through all visible views inside of a group. Once a view is selected it will be raised to the top of the stacking order. Selecting happens by releasing the modifier key.
  • group-hide — Hides all visible views of the group of the focused view. 🙈
  • group-lower — Lowers all visible views of the group of the focused view.
  • group-only — Hides all visible views not belonging to the group of the focused view.
  • group-raise — Raises all visible views of the group of the focused view. ⬆️

🧚 Layout actions

  • layout-apply-[a-z] — Applies the layout in the according register to the current workspace sheet. If the register happens to be empty this is a no-op. If the view that currently has focus can be tiled and is not borrowed it will get raised to the top of the stack.
  • layout-cycle-view-[next|prev|first|last] — Cycle to the next or previous group according to the layout order. Once a view is selected it will be raised to the top of the stacking order, the layout order will remain unchanged.
  • layout-exchange-view-[next|prev|main] — Swaps the focused view with the next, previous or main view in the layout order. 🔄
  • layout-reset — Resets the geometry of all views in the current layout.
  • layout-restack-[append|prepend] — Adds non-floating sheet views to an existing layout without changing layout order of already tiled views. If no layout is present the default layout for the current sheet is applied.

🌈 Mark actions

  • mark-show-[a-z] — Shows the view bound to the according mark. If no view is bound to the mark an optional command for this mark can be executed, if none is specified this action is a no-op.
  • mark-switch-to-[a-z] — Switches to the workspace containing the view bound to the according mark. If no view is bound to the mark an optional command for this mark can be executed, if none is specified this action is a no-op.

💜 Mode actions

  • mode-enter-group-assign — Entering group-assign-mode allows the user to change the group of the currently focused view. Groups that do no exist yet get created. Groups that become empty get destroyed. 🫧
  • mode-enter-input-grab — Redirect all input events directly to the focused view without the compositor interfering. Focus will not leave this view anymore until the mode exits or the view closes. To exit this mode, reissue the same key binding that started this mode. 🎯
  • mode-enter-layout — Layout selection awaits one of the layout registers to be selected. Valid registers range from a to z and 0 to 9. ESC cancels this mode without selecting a layout. If the layout register happens to be empty this action is a no-op. If the view that currently has focus can be tiled and is not borrowed it will get raised to the top of the stack. ✨
  • mode-enter-mark-assign — bestie, this is how you change the mark of a view. You enter mark assign mode and pick a mark between a and z. The way this works is that the mark indicator bar literally turns into an input field, iconic. Press Enter to lock in your choice, or ESC to bail. If that mark is already taken, hikari will point at the conflicting window for you. 💅
  • mode-enter-mark-select — mark selection lets you bring a view bound to a mark to the front by selecting that mark. When you enter this mode hikari just waits for you to issue the name of the mark. If that mark is bound to a view, that view gets shown — and if that view isn't a member of the current sheet, it's considered borrowed. If no view is bound to this mark, and the mark has been configured to execute a command when empty, then that command gets executed. periodt.
  • mode-enter-mark-switch-select — literally the same as mode-enter-mark-select except it also switches to the workspace of the bound view. If the mark isn't bound, you just stay on the same workspace. no drama.
  • mode-enter-move — moving views around with a pointer device, that's the whole vibe here. Once you enter it, the pointer jumps to the top left corner of the focused view and starts moving the view around with the pointer. Release any key and this mode is canceled automatically. 🦋
  • mode-enter-resize — same energy but for resizing with a pointer device. Once entered, the pointer joins to the bottom right corner of the focused view and starts resizing the view with the pointer. Release any key and this mode is canceled automatically. ✨
  • mode-enter-sheet-assign — entering this mode lets you change the sheet of a view by pressing the number of the target sheet. And if multiple outputs are available, you can cycle through them using TAB. 👑

Sheet actions 🎀

  • sheet-show-all — clears the current workspace and populates it with all views that are a member of its current sheet. This includes invisible views as well. fr fr.
  • sheet-show-group — clears the current workspace and populates it with all views that are a member of its current sheet and the group of the focused view. This includes invisible views as well.
  • sheet-show-invisible — clears the current workspace and populates it with all invisible views that are a member of its current sheet.

View actions 🌸

  • view-cycle-[next|prev] — cycle through all visible views. The next view is further up the stack, the previous view is further down the stack, and reaching each end of the stack just wraps around. Once a view is selected it gets raised to the top of the stacking order. The selecting happens when you release the modifier key. iykyk. 💖
  • view-decrease-size-[up|down|left|right] — decreases the size of the focused view by the amount of pixels set as step value into the given direction.
  • view-hide — hides the focused view. bye bestie 🫶
  • view-increase-size-[up|down|left|right] — increases the size of the focused view by the amount of pixels set as step value into the given direction.
  • view-lower — lowers the focused view to the bottom of the stacking order.
  • view-move-[up|down|left|right] — moves the focused view step pixels into the given direction.
  • view-move-[center[|-left|-right]|[bottom|top]-[left|middle|right]] — moves the focused view to the given position on the output.
  • view-only — hides every other view except the focused one. main character energy, truly.
  • view-pin-to-sheet-[0-9|alternate|current] — pins the focused view to a given sheet. If the sheet is not currently a current sheet or sheet 0, the view becomes hidden. Pinning a view to the current sheet makes sense for borrowed views, which takes this view from its original view and pins it to the current one.
  • view-quit — closes the focused view.
  • view-raise — raises the view to the top of the stacking order.
  • view-reset-geometry — resetting view geometry brings a view back to its original size and position. That means maximization gets undone, and the view also gets taken out of a layout if it was a part of one before.
  • view-snap-[up|down|left|right] — snap the focused view into the specified direction. Views can snap to the edge of the screen as well as to the borders of neighboring views (and in that case the gap setting is respected). 🧚
  • view-toggle-floating — toggles the floating state of the focused view. Floating views can not be part of a layout. If a view that's already tiled gets set to floating state, it will be taken out of the layout and reset its geometry.
  • view-toggle-invisible — toggles the invisible state of the focused view. A view in invisible state is not displayed if you switch to the sheet containing this view. They need to be shown explicitly, either by using marks or by issuing actions showing views in this state. Iconified views can not be part of a layout. If a view that's already tiled is set to invisible state, it will be taken out of the layout and reset its geometry.
  • view-toggle-maximize-[full|horizontal|vertical] — maximizes the focused view in the given direction. Maximization states complement each other, so maximizing a view horizontally and then vertically adds up to a full maximization state, and so on. the way that works >>> 💅
  • view-toggle-public — toggles the public state of the focused view. Public views are also displayed on the lock screen (note: they do not accept any input when the screen is locked though). These views should only contain information that should be displayed when the screen is locked, such as clocks or the progress of a long running process — they should never contain sensitive information. The public state is indicated in the sheet indicator bar via !.
⚠️ okay genuine warning time: public views go on your lock screen. Keep the sensitive stuff out of them, no cap. 🔒

VT actions ⭐

  • vt-switch-to-[1-9] — switches to another virtual terminal.

Workspace actions 🌈

  • workspace-clear — clears the current workspace.
  • workspace-cycle-[next|prev] — cycle through available workspaces, selecting the view that had focus last. If that view is no longer visible, the first view of the current sheet of that workspace is selected. In both cases the cursor gets centered on that view. And if the current sheet is empty, this moves the cursor into the center of the target workspace.
  • workspace-show-all — clears the current workspace and populates it with all views. This includes invisible views.
  • workspace-show-group — raises the focused view, clears the current workspace, and populates it with all views that are a member of the group of the focused view. This includes invisible views.
  • workspace-show-invisible — clears the current workspace and populates it with all invisible views that belong to that workspace.
  • workspace-switch-to-sheet-[0-9|alternate|current] — clears the current workspace and populates it with all views that are a member of the specified sheet. This action also sets the current sheet of the workspace to this very sheet. Views that are a member of sheet 0 will also be displayed on the bottom of the stacking order. Switching to the current sheet will reset the state of the sheet, e.g. hiding borrowed views, showing views that have previously been hidden, and hiding views that are in invisible state.
  • workspace-switch-to-sheet-[next|prev]-inhabited — switch to the next or previous sheet (excluding 00) that contains at least one member. If none exists it's a no-op. This action also sets the current sheet of the workspace to this sheet. 💜

🌟 USER DEFINED ACTIONS 🌟

Actions can also be user defined, bestie, and this is done in the actions section of the configuration file. A user defined action consists of a name and a command that should be run when the action has been issued.

So to define an action action-terminal that launches sakura(1), one needs to defined the following:

       terminal = sakura

Now we can bind the newly defined action-terminal to a key combination in the bindings section. slay. ✨

🎀 BINDINGS 🎀

Actions can be bound to keys and mouse buttons. The bindings section in the configuration file is used for this matter. Keys can be specified by using either key symbols or codes. A key combination starts with a string identifying the modifiers for the bindings. There are 5 valid modifiers. A valid modifier string is a combination of the following modifiers.

  • L (Logo)
  • S (Shift)
  • C (Control)
  • A (Alt)
  • 5 (AltGR)

If we want to omit the modifier for a key binding we signal this by using “0” instead of a modifier string.

Following the modifier string a key symbol or code can be stated. If we're using a key symbol to identify a key combination we're using “+” followed by the symbol; in the case of a key code we're using “-” followed by the numerical key code. Key symbols and codes can be determined using wev(1). 🦋

Once a key combination has been identified it can be bound to an action.

       "LS+a" = action1 # symbol binding
       "LS-38" = action2 # code binding

The bindings section can contain 2 subsections keyboard and mouse for keyboard and mouse bindings.

Valid values for mouse button names are right, middle, left, side, extra, forward, back and task.

Bindings can have a dedicated end action that gets triggered whenever a key is released or additional keys are pressed. It ensures that a begin action definitely is followed by the end action. obsessed with this tbh.

       "L+t"  = {
         begin = action-push-to-talk-start
         end = action-push-to-talk-stop
       }

💖 MARK CONFIGURATION 💖

Marks can be used to quickly navigate to views. They can also execute commands when they are not currently bound to a view. This functionality can be used to start an application that can then take over that mark using auto configuration. Note that the started application does not automatically take over the mark.

To specify commands that are issued on unassigned marks, one can specify the commands associated with the mark in the marks section in the configuration file.

       marks {
         s = sakura
       }

✨ VIEW CONFIGURATION ✨

okay so when an app starts, hikari can just... auto-configure its views for you 🫶 Every view has a lil property called id, and in the views section you can use that id to say exactly which properties you want to apply to that view. it's giving personalization era 💅

  • floating — takes a boolean, sets the view's floating state on startup. default is false. no cap.
  • focus — takes a boolean that says whether the view should automatically grab focus the first time it shows up. lowkey iconic for views that appear at a specific position. default is false.
  • group — automatically assign this view to a group (and bestie, if the group doesn't exist yet, it gets created automatically 💖). If you don't specify a group, a group name equal to the view id is chosen.
  • inherit — lets you list properties that should be inherited by child views (think dialogs, the little babies 🥺). To inherit a property just state its name as a string. You can also use an object to overwrite specific values if they should differ from the parent's config. Values that aren't explicitly inherited resort to their default. If inherit isn't specified, the child view is going to use the parent's configuration.
  • invisible — takes a boolean, sets the view's invisible state on startup. default is false.
  • mark — assign a mark to the view. this only takes effect if that mark isn't already bound to another view already. (so, first come first served, sorry ✋)
  • position — positions a newly created view at the given coordinates. hikari lets you define a view position two ways: one way is to specify an absolute position by stating the x and y coordinates as an object, the other one is by stating them as one of these options:
    • bottom-left
    • bottom-middle
    • bottom-right
    • center
    • center-left
    • center-right
    • top-left
    • top-middle
    • top-right

this lets you position a view relative to the output, slay ✨

  • public — takes a boolean, sets the view's public state on startup. default is false.
  • sheet — takes an integer that references the sheet this view should be assigned to. If the current sheet is unequal to this sheet, or 0, this view automatically is considered to be borrowed. 👀

so like, to configure views of the systat id to become a member of the group monitor and automatically assign them to sheet 0 with a given position and focus grabbing, we'd do something like this. Child views inherit the group and sheet property while overwriting floating to true, and all the other properties are set to their respective default values.

systat = {
  group = monitor
  sheet = 0
  position = {
    x = 1429
    y = 1077
  }
  focus = true

  inherit = [ group, sheet, { floating = true } ]
}

🌈 LAYOUTS 🌈

hikari is not a tiling compositor, so naturally some things behave a bit differently compared to traditional tiling approaches. first and foremost, hikari tries to minimize operations that affect a lot of views at the same time — like, opening a new view will not automatically insert a view into an existing layout and resize all of the already tiled views. to insert a view into an existing layout, the user has to issue a tiling action. this way opening a new view doesn't scramble an existing layout, and you get to actively decide when to incorporate a view into a layout. main character energy: you're in control 💅

a layout is bound to a sheet, each sheet can have at most one layout, and laying out a sheet will incorporate all of its views unless they're invisible or floating. resetting a layout will reset the geometry of all of the laid out views to its original geometry (also resetting maximization, fyi).

configuring layouts happens in the layouts section in the configuration file. Layouts are assigned to layout registers from a to z and special layout registers 0 to 9 which correspond to default layouts for a respective sheet. A layout itself is a combination of splits and containers with tiling algorithms.

Splits are used to subdivide regions of space and containers are used to consume views and layout them according to a specific tiling algorithm. let's get into it bestie 🎀

Splits

A layout subdivides the screen space using splits. Dividing up the screen space uses a binary space partitioning approach. You can split a region of space horizontally or vertically into two new regions, which can contain either another split or a container with a tiling algorithm.

To split up the screen vertically into two equally sized sections, you have to specify what the left and right hand side of the split should contain.

{
  left = ...
  right = ...
}

Respectively, to split horizontally you have to specify top and bottom.

Notice that the order in which you specify left, right, top and bottom is important, since it defines the orientation of the split. The side of the split that gets specified first is the part that gets filled first when tiling a sheet — it becomes the dominant part of the split. 👑

Sometimes splitting a region of space shouldn't result in equally sized subdivisions, and the dominant part of the split should be scaled up or down. This can be done by specifying the scale attribute, which can vary between 0.1 to 0.9. If no scale is specified this value defaults to 0.5.

To horizontally split a region of space where the top portion of the split should take up 75%, you'd specify it like so:

{
  scale = 0.75
  top = ...
  bottom = ...
}

Additionally to setting a fixed scale value, hikari allows you to specify a scale object with min and max values. This is called dynamic scaling, and it uses the size of the first view inside the container to determine the size of the entire container. The min and max values are used to specify possible minimum and maximum scale values for the container. Omitting the values for min or max sets the former to 0.1 and the latter to 0.9.

{
  scale = {
    min = 0.5
    max = 0.75
  }
  left = single
  right = stack
}

Containers

Containers consume a number of views and arrange them according to a tiling algorithm. There are 6 different tiling algorithms that you can assign to a container. let's meet the whole squad 💖

  • empty — this is one of the simplest algorithms, it does not consume any views. This is used if a user desires to have a container of a layout remain empty, e.g. preventing the layout to cover up a portion of the workspace.
  • single — containers using the single layout only consume one view, which takes up the entire container. one view, whole container, no notes ✨
  • full — each view inside of a container using this algorithm will take up the entire size of the container. All of the views are stacked up on top of each other.
  • stack — the stack algorithm tries to give every view the container consumes an equal amount of vertical space (excess space is given to the first view). The order in which stacking works is from top to bottom.
  • queue — the queue algorithm tries to give every view the container consumes an equal amount of horizontal space (excess space is given to the first view). The order in which stacking works is from left to right.
  • grid — a grid tries to give each view the container consumes an equal amount of horizontal and vertical space (excess space is given to the first view, and therefore first row of the grid). If the amount of views can not be split up into equal rows and columns, the last part of the grid will not be filled.

The easiest way to define a layout is by simply stating the tiling algorithm. Binding a fullscreen layout to the layout register f can be trivially achieved.

f = full

This layout does not subdivide the screen using splits in any way. The container takes up the entire screen space (respecting gap settings) and uses the full algorithm to arrange the views.

More complex layouts might demand that the user specifies the number of views that the container may contain, up to a maximum. This can be achieved by specifying a container object.

To define a queue container that contains up to 4 views, you'd define it like that:

{
  views = 4
  layout = queue
}

Just stating the tiling algorithm is a short-hand for a layout object where views is set to 256. (yes, 256, she's not subtle 🍓)

🌸 UI CONFIGURATION 🌸

okay bestie, getting everything to look right is a whole thing — it's literally how you feel "at home" in your setup 💖. hikari gives you a few little knobs to tweak the visuals however you want. All of these live in the ui section, periodt.

  • border — sets how thick view borders are, in pixels.

The standard border thickness is set to 1.

border = 1
  • gap — a gap is some extra space left between views when you're using a layout or snapping views. It's also just a pixel value.

The standard gap value is 5.

gap = 5
  • font — picks the font used for indicator bars.

hikari uses monospace 10 as its default font setting.

font = "monospace 10"
  • step — defines how many pixels move and resize operations should cover.

The standard step value is 100.

step = 100

🎀 Colorschemes 🎀

hikari uses color to show you the different states of views and their indicator bars. By specifying a colorscheme section you get to control all those colors yourself. A colorscheme is a bunch of properties you can change individually. Colors are specified using hexadecimal RGB values (e.g. 0xE6DB74) ✨.

  • active — indicates view focus.
  • background — specifies the background color. This will be obscured by a wallpaper.
  • conflict — conflicts can happen when you try to overwrite something (e.g. binding a mark to a view that's already taken up by another view) or do something illegal (e.g. defining a new group with a leading digit in its name) 💀.
  • first — signals that the indicated view is the topmost view of a group.
  • foreground — font color for indicator bars.
  • grouped — views that belong to the same group get indicated using this color.
  • inactive — indicates that a view does not have focus.
  • insert — indicates indicator bars that are in insert mode (e.g. assigning a view to a group) or views that have an input grab using mode-enter-input-grab.
  • selected — this color is used to indicate that a view is selected.

These are the default settings for the hikari colorscheme, no cap:

colorscheme {
  background = 0x282C34
  foreground = 0x000000
  selected   = 0xF5E094
  grouped    = 0xFDAF53
  first      = 0xB8E673
  conflict   = 0xED6B32
  insert     = 0xE3C3FA
  active     = 0xFFFFFF
  inactive   = 0x465457
}

🖱️ INPUTS 🖱️

The inputs section is where you configure your input devices. You can figure out device names using libinput(1) 👑.

Pointers

Pointers get configured in the pointers subsection. Here's what you've got to work with:

  • accel — sets mouse acceleration for the pointer device to a value between -1 and 1.
  • accel-profile — sets the mouse acceleration profile for the pointer device to the given mode. Valid values are none, flat and adaptive.
  • disable-while-typing — enable or disable disable-while-typing if available. This setting expects a boolean value.
  • middle-emulation — enable or disable middle click emulation if available. This setting expects a boolean value.
  • natural-scrolling — enable or disable natural-scrolling if available. This setting expects a boolean value.
  • scroll-button — configures the pointer scroll button. Valid values are right, middle, left, side, extra, forward, back and task.
  • scroll-method — sets the pointer's scroll method. Valid values are no-scroll, on-button-down.
  • tap — enable or disable tap if available. This setting expects a boolean value.
  • tap-drag — enable or disable tap-drag if available. This setting expects a boolean value.
  • tap-drag-lock — enable or disable tap-drag-lock if available. This setting expects a boolean value.

Configuring the System mouse input device could look like this, bestie:

inputs {
  pointers {
    "System mouse" = {
      accel = 1.0
      scroll-method = on-button-down
      scroll-button = middle
    }
  }
}

There's a special name "*" that addresses all pointers 💅. Values you define for this pseudo pointer override the unconfigured values for any other pointer.

Keyboards

hikari uses xkb to configure its keyboards, via the keyboards section. xkb rules can be set independently, or via a file using the xkb attribute.

To specify rules individually you can use these options — and hey, go peep xkeyboard-config(7) for all the possible settings:

  • rules — specifies the xkb rules. The default value is evdev.
  • model — sets the keyboard model.
  • layout — sets the keyboard layout.
  • variant — sets the keyboard variant.
  • options — sets keyboard options.

On top of that, hikari can also configure key repeat using these attributes:

  • repeat-delay — takes a positive integer to specify the key repeat delay in milliseconds. The default value is 600.
  • repeat-rate — takes a positive integer to specify the key repeat rate in Hz. The default value is 25.

Configuring the AT keyboard input device could look like this:

inputs {
  keyboards {
    "*" = {
      xkb = {
        layout = "de(nodeadkeys)"
        options = "caps:escape"
      }
      repeat-rate = 25
      repeat-delay = 600
    }
  }
}

A special name "*" is used to address all keyboards 🌈. Values defined for this pseudo keyboard override unconfigured values for any other pointer.

Keyboards can also be configured using XKB environment variables, and hikari will automatically fall back to these settings if a keyboard isn't explicitly configured:

  • XKB_DEFAULT_LAYOUT
  • XKB_DEFAULT_MODEL
  • XKB_DEFAULT_OPTIONS
  • XKB_DEFAULT_RULES

To specify a layout, set XKB_DEFAULT_LAYOUT to the desired layout. This needs to happen before starting hikari, okay?

XKB_DEFAULT_LAYOUT "de(nodeadkeys),de"

Switches

Switches get configured in the switches subsection 💜. A switch just takes an action and functions like a regular key binding, using the name of the switch as its identifier. The begin action is triggered when turning the switch on, and end is triggered when turning it off.

inputs {
  switches {
    "Control Method Lid Switch" = lock
  }
}

🖥️ OUTPUTS 🖥️

The outputs section lets you define the background and position for an output using its name 🦋. There's a special name "*" that addresses all outputs. Values defined for this pseudo output override unconfigured values for any other output.

Backgrounds are configured via the background attribute, which can be either the path to the background image, or an object that lets you define additional attributes for the background image. Background file format has to be PNG, fyi.

When you're defining a background object, these attributes are available:

  • path — this attribute giving the path to the wallpaper image file is mandatory.
  • fit — specifies how the wallpaper should be displayed. Available options are center, stretch and tile. stretch is the default even when specifying the background image as a string.

Configuring output eDP-1 and WL-1 could look like this:

outputs {
  "eDP-1" = {
    background = "/path/to/wallpaper"
  }

  WL-1 = {
    background = {
      path = "/path/to/wallpaper"
      fit = center
    }
  }
}

Output position can be given explicitly using the position attribute ✨. If none is given during startup, hikari will automatically configure the output.

"eDP-1" = {
  position = {
    x = 1680
    y = 0
  }
}

"HDMI-A-1" = {
  position = {
    x = 0
    y = 0
  }
}

aaaand that's the whole page bestie, we made it 🫶💖 this was hikari version 2.3.3, living in section HIKARI(1) of the manual — go forth and slay your config, you've got this 👑🌸

📦 where this page comes from