You can get plugins from awesome [BitBar repository](https://github.com/matryer/bitbar-plugins), or in SwiftBar itself using the `Get Plugins...` menu item.
If you want to add\remove plugin or have other questions about repository content please refer to this [issue](https://github.com/swiftbar/swiftbar-plugins/issues/1).
Whether you are using a plugin from the plugin repository, or creating your own, plugins will initially appear in the menu bar in no pre-determined order. However, you can reorder how they appear by holding down <kbd>Cmd</kbd> and dragging them (this process can sometimes also be used on some other non-SwiftBar icons in the menu bar too). Plugin position will be remembered unless you change the name of the plugin file, in which case they'll need to be re-positioned again.
Plugin is an executable script in the language of your choice. When SwiftBar detects a new file in `Plugin Folder` it makes this file executable if needed and runs it.
- **"Item Title"** can be any string, this will be used as a menu item title.
- **[param = ...]** is an optional set of parameters\modificators. Each parameter is a key-value separated by `=`. Use `|` to separate parameters from the title.
| `color` | CSS color or HEX, `light_color,dark_color` | Sets item text color. If only one color is provided, it is used for both light and dark appearance. |
| `sfcolor` | CSS color or HEX, `light_color,dark_color` | Sets SF Symbol color. If only one color is provided, it is used for both light and dark appearance. If you fame multiple SF Symbols you can provide different colors by adding index, like this `sfcolor2` |
| `dropdown` | False | Only applicable to items in `Header`. When set to False, item will not be displayed in dropdown menu, but will be cycled in the menu bar. |
| `alternate` | True | Marks a line as an alternative to the previous one for when the Option key (<kbdstyle="font-size:medium">⌥</kbd>) is pressed in the dropdown.|
| `image` | Image encoded in Base64, `light_image,dark_image` | Sets an image for item. If only one image is provided, it is used for both light and dark appearance.|
| `templateImage` | Image encoded in Base64| Same as `image`, but the image is a template image. Template images consist of black and clear colors (and an alpha channel). Template images are not intended to be used as standalone images and are usually mixed with other content to create the desired final appearance.|
| `shortcut` | CMD+OPTION+T | Hotkey assigned to item. If item is in header, hotkey will show the menu; otherwise, hotkey will launch associated action. |
*`<swiftbar.environment>[var1=default value, var2=default value, ... ]</swiftbar.environment>` - this variables will be passed in plugin's environment, in later release SwiftBar will provide a UI to change values for these variables.
This plugin type is aimed for people who want to use Shortcuts app to create menu bar items. The Plugin API is pretty much the same as Standard. Create a Shortcut that outputs text in the required format, select this Shortcut in the Shortcuts Plugin section of SwiftBar's Settings, and you are good to go.
For Shortcuts plugins, SwiftBar provides a handy UI to configure refresh schedule.
Ephemeral plugins create menu bar items on demand by running SwiftBar's Shortcut action or calling a URL scheme. The Plugin API is pretty much the same as Standard.
Here are the parameters for the URL scheme:
- name - this is the plugin name, should be unique
- content - this is the markup you want SwiftBar to render
- exitafter - this is optional parameter forces plugin to exit after a period of time, set in seconds.. Defaults to 0, which means "don't exit".
Shortcuts Action is pretty self-explanatory.
This plugin type is best used for notifications or other temporary menu bar items.
You should use Streamable plugins only when dealing with a stream of incoming events; an example could be financial market info read from a websocket or CPU load information for a remote computer.
To let SwiftBar know when to update the menu bar item, Streamable plugins must use a special line separator `~~~`. SwiftBar will reset the menu item on each occurrence of this separator.
In the example below, SwiftBar will show "Test 1" in the menu bar for 3 seconds, then nothing for 5 seconds, and "Test 2" indefinitely.
```
#!/bin/bash
#<swiftbar.type>streamable</swiftbar.type>
echo "Test 1"
echo "---"
echo "Test 2"
echo "Test 3"
sleep 3
echo "~~~"
sleep 5
echo "~~~"
echo "Test 2"
```
You can mark a plugin as streamable with a special metadata property `<swiftbar.type>streamable</swiftbar.type>`
* Instead of the plugin [name](#plugin-naming), you can (and probably should) use the plugin file name. This considered a unique plugin ID, whereas `name` can be the same between multiple plugins. If your plugin's filepath is `~/Documents/SwiftBar/myplugin.1m.sh`, then the name is `myplugin` and the ID `myplugin.1m.sh`
* When using `open(1)` to trigger scheme URLs, use `-g` to prevent the command from stealing focus from your active app.
| refreshplugin | `name` or `plugin` plugin [name](#plugin-naming) | Force refresh plugin by name. If provided, additional URL parameters are exposed as ENV variables to the plugin | `swiftbar://refreshplugin?name=myplugin` |
| refreshplugin | `index` plugin index in menubar, starting from `0` | Force refresh plugin by its position in menubar | `swiftbar://refreshplugin?index=1` |
| notify | `name` or `plugin` plugin [name](#plugin-naming). Notification fields: `title`, `subtitle`, `body`. `href` to open an URL on click (including custom URL schemes). `silent=true` to disable sound | Show notification | `swiftbar://notify?plugin=MyPlugin&title=title&subtitle=subtitle&body=body&silent=true` |
| setephemeralplugin | `name` plugin name, should be unique. `content` - plugin content, `exitafter` - optionally set the lifetime of the menubar in seconds | Creates an Ephemeral Plugin. To remove existing Ephemeral Plugin set it's content to an empty string `""` | `swiftbar://setephemeralplugin?name=ephemeral&content=hi` |
*`defaults write com.ameba.SwiftBar StreamablePluginDebugOutput -bool YES` - enables debug output for Streamable plugins, Swiftbar will expose the stream data in Console.App