{"id":13532636,"url":"https://github.com/outfoxxed/hy3","last_synced_at":"2026-01-12T09:38:51.789Z","repository":{"id":153581394,"uuid":"625666619","full_name":"outfoxxed/hy3","owner":"outfoxxed","description":"Hyprland plugin for an i3 / sway like manual tiling layout","archived":false,"fork":false,"pushed_at":"2025-05-12T19:14:39.000Z","size":461,"stargazers_count":709,"open_issues_count":36,"forks_count":59,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-05-15T07:03:30.674Z","etag":null,"topics":["hyprland","hyprland-plugin"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/outfoxxed.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-04-09T20:13:01.000Z","updated_at":"2025-05-15T03:36:19.000Z","dependencies_parsed_at":"2023-09-22T18:50:46.719Z","dependency_job_id":"ea504429-3258-471c-b311-69b104161cf1","html_url":"https://github.com/outfoxxed/hy3","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outfoxxed%2Fhy3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outfoxxed%2Fhy3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outfoxxed%2Fhy3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outfoxxed%2Fhy3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/outfoxxed","download_url":"https://codeload.github.com/outfoxxed/hy3/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254291961,"owners_count":22046424,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hyprland","hyprland-plugin"],"created_at":"2024-08-01T07:01:12.484Z","updated_at":"2026-01-12T09:38:51.781Z","avatar_url":"https://github.com/outfoxxed.png","language":"C++","funding_links":[],"categories":["Plugins","C++"],"sub_categories":[],"readme":"\u003cimg align=\"right\" style=\"width: 256px\" src=\"assets/logo.svg\"\u003e\n\n# hy3\n\u003ca href=\"https://matrix.to/#/#hy3:outfoxxed.me\"\u003e\u003cimg src=\"https://img.shields.io/badge/Join%20the%20matrix%20room-%23hy3:outfoxxed.me-0dbd8b?logo=matrix\u0026style=flat-square\"\u003e\u003c/a\u003e\n\ni3 / sway like layout for [hyprland](https://github.com/hyprwm/hyprland).\n\n[Installation](#installation), [Configuration](#configuration)\n\n*Check the [changelog](./CHANGELOG.md) for a list of new features and improvements*\n\n### Features\n- [x] i3 like tiling\n- [x] Node based window manipulation (you can interact with multiple windows at once)\n- [x] Greatly improved tabbed node groups over base hyprland\n- [x] Optional autotiling\n\nAdditional features may be suggested in the repo issues or the [matrix room](https://matrix.to/#/#hy3:outfoxxed.me).\n\n### Demo\n\u003cvideo width=\"640\" height=\"360\" controls=\"controls\" src=\"https://github.com/user-attachments/assets/ed2fe78d-8c31-47d8-a91d-e89aed42189c\"\u003e\u003c/video\u003e\n\n-----\n\nIn addition to hy3, I maintain [Quickshell](https://quickshell.outfoxxed.me/?utm_source=hy3-readme),\na toolkit for creating custom bars, widgets, lockscreens, and other desktop shell components\nwith first class support for Hyprland.\n\nIf that sounds interesting, check out the [website](https://quickshell.outfoxxed.me/?utm_source=hy3-readme).\n\n-----\n\n### Stability\nhy3 has a tagged release for each hyprland update, and master tracks hyprland's main branch.\nIf you are running a release version of hyprland then use the matching tagged hy3 version.\nIf you are running an untagged hyprland release then use the `master` branch of hy3.\n\nCommits are tested before pushing and will build against the hyprland release **in the flake.lock file**.\nThere may be a mismatch with hyprland's main branch. If hy3 fails to build against hyprland's main branch\nplease make an issue or ping me in the [hy3 matrix room](https://matrix.to/#/#hy3-support:outfoxxed.me).\n\nTagged hy3 versions are always checked against the corresponding hyprland tag.\n\nIf you encounter any bugs, please report them in the issue tracker.\n\nWhen reporting bugs, please include:\n- Commit hash of the version you are running.\n- Steps to reproduce the bug (if you can figure them out)\n- backtrace of the crash (if applicable)\n\n## Installation\n\n\u003e [!IMPORTANT]\n\u003e The master branch of hy3 follows the master branch of hyprland.\n\u003e Attempting to use a mismatched hyprland release will result in failure when building or loading hy3.\n\u003e\n\u003e To use hy3 against a release version of hyprland,\n\u003e check out the matching hy3 tag for the hyprland version.\n\u003e hy3 tags are formatted as `hl{version}` where `{version}` matches the release version of hyprland.\n\n### Nix\n#### Hyprland home manager module\nAssuming you use hyprland's home manager module, you can easily integrate hy3 by adding it to the plugins array.\n\n```nix\n# flake.nix\n\n{\n  inputs = {\n    nixpkgs.url = \"github:NixOS/nixpkgs/nixos-unstable\";\n\n    home-manager = {\n      url = \"github:nix-community/home-manager\";\n      inputs.nixpkgs.follows = \"nixpkgs\";\n    };\n\n    hyprland.url = \"git+https://github.com/hyprwm/Hyprland?submodules=1\u0026ref={version}\";\n    # where {version} is the hyprland release version\n    # or \"github:hyprwm/Hyprland?submodules=1\" to follow the development branch\n\n    hy3 = {\n      url = \"github:outfoxxed/hy3?ref=hl{version}\"; # where {version} is the hyprland release version\n      # or \"github:outfoxxed/hy3\" to follow the development branch.\n      # (you may encounter issues if you dont do the same for hyprland)\n      inputs.hyprland.follows = \"hyprland\";\n    };\n  };\n\n  outputs = { nixpkgs, home-manager, hyprland, hy3, ... }: {\n    homeConfigurations.\"user@hostname\" = home-manager.lib.homeManagerConfiguration {\n      pkgs = nixpkgs.legacyPackages.x86_64-linux;\n\n      modules = [\n        hyprland.homeManagerModules.default\n\n        {\n          wayland.windowManager.hyprland = {\n            enable = true;\n            plugins = [ hy3.packages.x86_64-linux.hy3 ];\n          };\n        }\n      ];\n    };\n  };\n}\n```\n\n#### Manual (Nix)\nhy3's binary is availible as `${hy3.packages.\u003csystem\u003e.hy3}/lib/libhy3.so`, so you can also\ndirectly use it in your hyprland config like so:\n\n```nix\n# ...\nwayland.windowManager.hyprland = {\n  # ...\n  extraConfig = ''\n    plugin = ${hy3.packages.x86_64-linux.hy3}/lib/libhy3.so\n  '';\n};\n```\n\n### hyprpm\nHyprland now has a dedicated plugin manager, which should be used when your package manager\nisn't capable of locking hy3 builds to the correct hyprland version.\n\n\u003e [!IMPORTANT]\n\u003e Make sure hyprpm is activated by putting\n\u003e\n\u003e ```conf\n\u003e exec-once = hyprpm reload -n\n\u003e ```\n\u003e\n\u003e in your hyprland.conf. (See [the wiki](https://wiki.hyprland.org/Plugins/Using-Plugins/) for details.)\n\nTo install hy3 via hyprpm run\n\n```sh\nhyprpm add https://github.com/outfoxxed/hy3\n```\n\nTo update hy3 (and all other plugins), run\n\n```sh\nhyprpm update\n```\n\nSometimes the headers from hyprland are not updated, if this happens run (See [issue #109](https://github.com/outfoxxed/hy3/issues/109) for an example of where this happened)\n\n```sh\nhyprpm update -f\n```\n\n(See [the wiki](https://wiki.hyprland.org/Plugins/Using-Plugins/) for details.)\n\n\u003e [!WARNING]\n\u003e When you are running a tagged hyprland version hyprpm (0.34.0+) will build against hy3's\n\u003e corrosponding release. However if you are running an untagged build (aka `-git`) hyprpm\n\u003e will build against hy3's *latest* commit. This means **if you are running an out of date\n\u003e untagged build of hyprland, hyprpm may pick an incompatible revision of hy3**.\n\u003e\n\u003e To fix this problem you will either need to update hyprland or manually build the correct\n\u003e version of hy3.\n\n### Manual\nInstall hyprland, including its headers and pkg-config file, then run the following commands:\n\n```sh\ncmake -DCMAKE_BUILD_TYPE=Release -B build\ncmake --build build\n```\n\nThe plugin will be located at `build/libhy3.so`, and you can load it normally\n(See [the hyprland wiki](https://wiki.hyprland.org/Plugins/Using-Plugins/#installing--using-plugins) for details.)\n\nNote that the hyprland headers and pkg-config file **MUST be installed correctly, for the target version of hyprland**.\n\n### Arch (AUR)\n\n\u003e [!NOTE]\n\u003e This method of installation is deprecated and you should use *hyprpm* instead,\n\u003e as it is simpler and less error prone.\n\n\u003e [!CAUTION]\n\u003e Pacman is not very reliable when it comes to building packages in the correct order.\n\u003e If you get a notification saying *hy3 was compiled for a different version of hyprland*\n\u003e then your packages likely updated in the wrong order, or you have hyprland headers in `/usr/local`.\n\u003e\n\u003e To fix this, remove `/usr/include/hyprland`, `/usr/local/include/hyprland`, `/usr/share/pkgconfig/hyprland.pc` and `/usr/local/share/pkgconfig/hyprland.pc`,\n\u003e then reinstall hyprland and hy3.\n\u003e\n\u003e If you know how to fix this please open an issue or pr, or message `@outfoxxed:outfoxxed.me` in the [matrix room](https://matrix.to/#/#hy3-support:outfoxxed.me).\n\nhy3 stable (for arch's `hyprland` package) is availible on the AUR as [hy3](https://aur.archlinux.org/packages/hy3).\n\nhy3-git (for `hyprland-git` on the AUR, unofficial package) is availible on the AUR as [hy3-git](https://aur.archlinux.org/packages/hy3-git).\n\nBoth packages install hy3 as `/usr/lib/libhy3.so`.\nYou can enable it in your hyprland configuration by adding the following line anywhere in your `hyprland.conf`\n\n```conf\nplugin = /usr/lib/libhy3.so\n```\n\n## Configuration\n\n\u003e [!IMPORTANT]\n\u003e The configuration listed below is for the current hy3 commit.\n\u003e If you are using a release version of hy3 then make sure you are\n\u003e reading the tagged revision of this readme.\n\nSet your `general:layout` to `hy3` in hyprland.conf.\n\nhy3 requires using a few custom dispatchers for normal operation.\nIn your hyprland config replace the following dispatchers:\n - `movefocus` -\u003e `hy3:movefocus`\n - `movewindow` -\u003e `hy3:movewindow`\n\nYou can use `hy3:makegroup` to create a new split.\n\nThe [dispatcher list](#dispatcher-list) and [config fields](#config-fields) sections have all the\nconfiguration options, and some explanation as to what they do.\n[The hyprland config in my dots](https://git.outfoxxed.me/outfoxxed/nixnew/src/branch/master/modules/hyprland/hyprland.conf) can also be used as a reference.\n\n### Config fields\n```conf\nplugin {\n  hy3 {\n    # disable gaps when only one window is onscreen\n    # 0 - always show gaps\n    # 1 - hide gaps with a single window onscreen\n    # 2 - 1 but also show the window border\n    no_gaps_when_only = \u003cint\u003e # default: 0\n\n    # policy controlling what happens when a node is removed from a group,\n    # leaving only a group\n    # 0 = remove the nested group\n    # 1 = keep the nested group\n    # 2 = keep the nested group only if its parent is a tab group\n    node_collapse_policy = \u003cint\u003e # default: 2\n\n    # offset from group split direction when only one window is in a group\n    group_inset = \u003cint\u003e # default: 10\n\n    # if a tab group will automatically be created for the first window spawned in a workspace\n    tab_first_window = \u003cbool\u003e\n\n    # tab group settings\n    tabs {\n      # height of the tab bar\n      height = \u003cint\u003e # default: 22\n\n      # padding between the tab bar and its focused node\n      padding = \u003cint\u003e # default: 6\n\n      # the tab bar should animate in/out from the top instead of below the window\n      from_top = \u003cbool\u003e # default: false\n\n      # radius of tab bar corners\n      radius = \u003cint\u003e # default: 6\n\n      # tab bar border width\n      border_width = \u003cint\u003e # default: 2\n\n      # render the window title on the bar\n      render_text = \u003cbool\u003e # default: true\n\n      # center the window title\n      text_center = \u003cbool\u003e # default: true\n\n      # font to render the window title with\n      text_font = \u003cstring\u003e # default: Sans\n\n      # height of the window title\n      text_height = \u003cint\u003e # default: 8\n\n      # left padding of the window title\n      text_padding = \u003cint\u003e # default: 3\n\n      # active tab bar segment colors\n      col.active = \u003ccolor\u003e # default: rgba(33ccff40)\n      col.active.border = \u003ccolor\u003e # default: rgba(33ccffee)\n      col.active.text = \u003ccolor\u003e # default: rgba(ffffffff)\n\n      # active tab bar segment colors for bars on an unfocused monitor\n      col.active_alt_monitor = \u003ccolor\u003e # default: rgba(60606040)\n      col.active_alt_monitor.border = \u003ccolor\u003e # default: rgba(808080ee)\n      col.active_alt_monitor.text = \u003ccolor\u003e # default: rgba(ffffffff)\n\n      # focused tab bar segment colors (focused node in unfocused container)\n      col.focused = \u003ccolor\u003e # default: rgba(60606040)\n      col.focused.border = \u003ccolor\u003e # default: rgba(808080ee)\n      col.focused.text = \u003ccolor\u003e # default: rgba(ffffffff)\n\n      # inactive tab bar segment colors\n      col.inactive = \u003ccolor\u003e # default: rgba(30303020)\n      col.inactive.border = \u003ccolor\u003e # default: rgba(606060aa)\n      col.inactive.text = \u003ccolor\u003e # default: rgba(ffffffff)\n\n      # urgent tab bar segment colors\n      col.urgent = \u003ccolor\u003e # default: rgba(ff223340)\n      col.urgent.border = \u003ccolor\u003e # default: rgba(ff2233ee)\n      col.urgent.text = \u003ccolor\u003e # default: rgba(ffffffff)\n\n      # urgent tab bar segment colors\n      col.locked = \u003ccolor\u003e # default: rgba(90903340)\n      col.locked.border = \u003ccolor\u003e # default: rgba(909033ee)\n      col.locked.text = \u003ccolor\u003e # default: rgba(ffffffff)\n\n      # if tab backgrounds should be blurred\n      # Blur is only visible when the above colors are not opaque.\n      blur = \u003cbool\u003e # default: true\n\n      # opacity multiplier for tabs\n      # Applies to blur as well as the given colors.\n      opacity = \u003cfloat\u003e # default: 1.0\n    }\n\n    # autotiling settings\n    autotile {\n      # enable autotile\n      enable = \u003cbool\u003e # default: false\n\n      # make autotile-created groups ephemeral\n      ephemeral_groups = \u003cbool\u003e # default: true\n\n      # if a window would be squished smaller than this width, a vertical split will be created\n      # -1 = never automatically split vertically\n      # 0 = always automatically split vertically\n      # \u003cnumber\u003e = pixel width to split at\n      trigger_width = \u003cint\u003e # default: 0\n\n      # if a window would be squished smaller than this height, a horizontal split will be created\n      # -1 = never automatically split horizontally\n      # 0 = always automatically split horizontally\n      # \u003cnumber\u003e = pixel height to split at\n      trigger_height = \u003cint\u003e # default: 0\n\n      # a space or comma separated list of workspace ids where autotile should be enabled\n      # it's possible to create an exception rule by prefixing the definition with \"not:\"\n      # workspaces = 1,2 # autotiling will only be enabled on workspaces 1 and 2\n      # workspaces = not:1,2 # autotiling will be enabled on all workspaces except 1 and 2\n      workspaces = \u003cstring\u003e # default: all\n    }\n  }\n}\n```\n\n### Dispatcher list\n - `hy3:makegroup, \u003ch | v | opposite | tab\u003e, [toggle], [ephemeral | force_ephemeral]` - make a vertical / horizontal split or tab group\n   - `toggle` - if the focused node is the only child of its parent, which is of the type specified, the node's parent will be removed.\n   - `ephemeral` - the group will be removed once it contains only one node. does not affect existing groups.\n   - `force_ephemeral` - same as ephemeral, but converts existing single windows groups.\n - `hy3:changegroup, \u003ch | v | tab | untab | toggletab | opposite\u003e` - change the group the node belongs to, to a different layout\n   - `untab` will untab the group if it was previously tabbed\n   - `toggletab` will untab if group is tabbed, and tab if group is untabbed\n   - `opposite` will toggle between horizontal and vertical layouts if the group is not tabbed.\n - `hy3:setephemeral, \u003ctrue | false\u003e` - change the ephemerality of the group the node belongs to\n - `hy3:movefocus, \u003cl | u | d | r | left | down | up | right\u003e, [visible], [warp | nowarp]` - move the focus left, up, down, or right\n   - `visible` - only move between visible nodes, not hidden tabs\n   - `warp` - warp the mouse to the selected window, even if `general:no_cursor_warps` is true.\n   - `nowarp` - does not warp the mouse to the selected window, even if `general:no_cursor_warps` is false.\n - `hy3:warpcursor` - warp the cursor to the center of the focused node\n - `hy3:movewindow, \u003cl | u | d | r | left | down | up | right\u003e, [once], [visible]` - move a window left, up, down, or right\n   - `once` - only move directly to the neighboring group, without moving into any of its subgroups\n   - `visible` - only move between visible nodes, not hidden tabs\n - `hy3:movetoworkspace, \u003cworkspace\u003e, [follow, [warp | nowarp]]` - move the active node to the given workspace\n   - `follow` - change focus to the given workspace when moving the selected node\n   - `warp` - warp the mouse to the selected window, even if `general:no_cursor_warps` is true.\n   - `nowarp` - does not warp the mouse to the selected window, even if `general:no_cursor_warps` is false.\n - `hy3:killactive` - close all windows in the focused node\n - `hy3:changefocus, \u003ctop | bottom | raise | lower | tab | tabnode\u003e`\n   - `top` - focus all nodes in the workspace\n   - `bottom` - focus the single root selection window\n   - `raise` - raise focus one level\n   - `lower` - lower focus one level\n   - `tab` - raise focus to the nearest tab\n   - `tabnode` - raise focus to the nearest node under the tab\n - `hy3:togglefocuslayer, [nowarp]` - toggle focus between tiled and floating layers\n   - `nowarp` - do not warp the mouse to the newly focused window\n - `hy3:focustab, [l | r | left | right | index, \u003cindex\u003e], [prioritize_hovered | require_hovered], [wrap]`\n   - `l | r | left | right` - direction to change focus towards\n   - `index, \u003cindex\u003e` - select the `index`th tab\n   - `prioritize_hovered` - prioritize the tab group under the mouse when multiple are stacked. use the lowest group if none is under the mouse.\n   - `require_hovered` - affect the tab group under the mouse. do nothing if none are hovered.\n   - `wrap` - wrap to the opposite size of the tab bar if moving off the end\n - `hy3:locktab, [lock | unlock]` - lock the current tab, makingg it behave like a node\n - `hy3:debugnodes` - print the node tree into the hyprland log\n - :warning: **ALPHA QUALITY** `hy3:setswallow, \u003ctrue | false | toggle\u003e` - set the containing node's window swallow state\n - :warning: **ALPHA QUALITY** `hy3:expand, \u003cexpand | shrink | base\u003e` - expand the current node to cover other nodes\n   - `expand` - expand by one node\n   - `shrink` - shrink by one node\n   - `base` - undo all expansions\n - `hy3:equalize, [workspace]` - equalize window sizes in group\n   - no argument: equalizes immediate siblings of the focused window\n   - `workspace`: equalizes all windows across the entire workspace tree\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foutfoxxed%2Fhy3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foutfoxxed%2Fhy3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foutfoxxed%2Fhy3/lists"}