Crawraps' Widgets Collection

A customizable collection of widgets built with the quickshell environment.

cwc-example-config.mp4

Table of Contents

• Installation
  • Manual Installation
• Usage
• Configuration
  • Appearance Configuration
  • Widgets Configuration
• Widgets
  • Dock
• Contributing
• Future Plans

Installation

Manual Installation

1. Dependencies:
   Install the core dependency - quickshell

   Some widgets may require additional dependencies for extra features. Read the widget overview before using them.

2. Clone the Repository:

   $ git clone https://github.com/crawraps/widgets-collection $HOME/.config/quickshell/cwc

   If $XDG_CONFIG_HOME is not defined, use $HOME/.config instead.

Usage

1. Select the widgets you want to use by editing the shell.qml file. Example:

// shell.qml

...

ShellRoot {
  Dock {} // dock widget with the default configuration
}

Each widget creates an instance for each monitor by default. You can configure this behavior—read the configuration section for details.

2. Start the shell by typing $ quickshell -c cwc or $ quickshell -dc cwc to run as a daemon.
3. *Optional* Add the command above to system startup. For example, in Hyprland, add exec-once=quickshell -dc cwc to your hyprland.conf.
4. *Optional* Create an alias for better usability. For example, in zsh, add alias -- cwc='quickshell -c cwc' to your .zshrc.

Configuration

You can configure widgets and their appearance by modifying .json files. Every config file supports hot-reload.

Appearance Configuration

Global appearance (colors, fonts, spacing, etc.) is managed via appearance.json in your config directory (e.g., $HOME/.config/quickshell/cwc/appearance.json):

{
  "colors": {
    "primary": "#007acc",
    "background": "#20242b"
  },
  "font": {
    "family": { "regular": "Fira Sans" },
    "size": { "xm": 10 }
  },
  "spacing": { "small": 8 },
  "rounding": { "small": 4, "medium": 8 },
  "animation": { "duration": { "normal": 200, "sequential": 50 } },
  "opacity": 0.85
}

Widgets Configuration

Each widget can have several widget-specific .json configuration files, each located in the widgets/[widget-name]/configs/ directory.

When selecting a widget to use, you can provide several common options:

// shell.qml

...

  Dock {
    name: "power-menu"
    screenIds: [0]
    screens: [Quickshell.screens.reduce((acc, screen) => screen.x > acc.x ? screen : acc, { x: -Infinity })]
  }

• name: Name of a .json configuration file. Default value is "default". In this example, it would be widgets/dock/configs/power-menu.json.
• screenIds: List of screen IDs where the widget should be displayed. Default: every screen.
• screens: List of screens where the widget should be displayed. When this option is present, the screenIds option will be ignored. Use this for more precise configuration: in the example above, the widget will be displayed on the rightmost screen.

Widgets

Dock

Showcase

applications-dock-example.mp4

power-menu-dock-example.mp4

Each dock can be configured with a JSON file (e.g., configs/applications.json):

{
  "position": "bottom",
  "orientation": "horizontal",
  "margins": {
    "right": 200
  },
  "items": [
    "Zen",
    "Obsidian",
    "Thunderbird"
  ],
  "iconSize": 48,
  "alwaysVisible": false,
  "showIconsBackground": true,
  "showTooltips": true,
  "falloff": 3,
  "scaleFactor": 0.3,
  "damp": 1
}

• position: "top", "bottom", "left", "right" - where to position the dock
• orientation: "horizontal" or "vertical" - how to orient the dock
• margins: { "bottom": number, "top": number, "right": number, "left": number } - spacing from screen edges. By default, the dock will be centered on the specified position edge
• items: List of .desktop file app names to show; if not defined, all desktop applications will be listed
• iconSize: Size of an icon in pixels
• alwaysVisible: If false, the dock expands/collapses on hover
• showIconsBackground: Whether to show background for icons
• showTooltips: Whether to display tooltips
• falloff: Number of items to be affected by hover animation
• scaleFactor: Controls item's hover scaling animation strength
• damp: Controls nearby items' hover scaling animation strength

Contributing

If you have new ideas, concepts or implementations, consider contributing to this collection.

There are no guidelines yet, so I would appreciate following the existing architecture with examples of existing widgets.

Future Plans

Here's a list of widgets I want to create:

• dock
• launcher
• translator/dictionary
• weather display
• emoji picker
• mpris
• system info display
• feature-rich calendar