Skip to main content

Widgets

Dashy has support for displaying dynamic content in the form of widgets. There are several built-in widgets available out-of-the-box as well as support for custom widgets to display stats from almost any service with an API.

ℹī¸ Note: Widgets are still in the Alpha-phase of development. If you find a bug, please raise it.
Adding / editing widgets through the UI isn't yet supported, you will need to do this in the YAML config file.

Contents#

General Widgets#

Clock#

A simple, live-updating time and date widget with time-zone support. All fields are optional.

Options#
FieldTypeRequiredDescription
timeZonestringOptionalThe time zone to display date and time in.
Specified as Region/City, for example: Australia/Melbourne. See the Time Zone DB for a full list of supported TZs. Defaults to the browser / device's local time
formatstringOptionalA country code for displaying the date and time in local format.
Specified as [ISO-3166]-[ISO-639], for example: en-AU. See here for a full list of locales. Defaults to the browser / device's region
customCityNamestringOptionalBy default the city from the time-zone is shown, but setting this value will override that text
hideDatebooleanOptionalIf set to true, the date and city will not be shown. Defaults to false
Example#
- type: clock  options:    timeZone: Europe/London    format: en-GB    hideDate: false
Info#

No external data requests

Weather#

A simple, live-updating local weather component, showing temperature, conditions and more info.

Options#
FieldTypeRequiredDescription
apiKeystringRequiredYour OpenWeatherMap API key. You can get one for free at openweathermap.org
citystringRequiredA city name to use for fetching weather. This can also be a state code or country code, following the ISO-3166 format
unitsstringOptionalThe units to use for displaying data, can be either metric or imperial. Defaults to metric
hideDetailsbooleanOptionalIf set to true, the additional details (wind, humidity, pressure, etc) will not be shown. Defaults to false
Example#
- type: weather  options:    apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx    city: London    units: metric    hideDetails: false
Info#
  • CORS: đŸŸĸ Enabled
  • Auth: 🔴 Required
  • Price: 🟠 Free plan
  • Privacy: See OWM Privacy Policy

Weather Forecast#

Displays the weather (temperature and conditions) for the next few days for a given location. Note that this requires either the free OpenWeatherMap Student Plan, or the Premium Plan.

Options#
FieldTypeRequiredDescription
apiKeystringRequiredYour OpenWeatherMap API key. You can get one at openweathermap.org or for free via the OWM Student Plan
citystringRequiredA city name to use for fetching weather. This can also be a state code or country code, following the ISO-3166 format
numDaysnumberOptionalThe number of days to display of forecast info to display. Defaults to 4, max 16 days
unitsstringOptionalThe units to use for displaying data, can be either metric or imperial. Defaults to metric
hideDetailsbooleanOptionalIf set to true, the additional details (wind, humidity, pressure, etc) will not be shown. Defaults to false
Example#
- type: weather-forecast  options:    city: California    numDays: 6    apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx    units: imperial
Info#
  • CORS: đŸŸĸ Enabled
  • Auth: 🔴 Required
  • Price: 🔴 Premium (free for personal use only)
  • Privacy: See OWM Privacy Policy

RSS Feed#

Display news and updates from any RSS-enabled service.

Options#
FieldTypeRequiredDescription
rssUrlstringRequiredThe URL location of your RSS feed
apiKeystringOptionalAn API key for rss2json. It's free, and will allow you to make 10,000 requests per day, you can sign up here
limitnumberOptionalThe number of posts to return. If you haven't specified an API key, this will be limited to 10
orderBystringOptionalHow results should be sorted. Can be either pubDate, author or title. Defaults to pubDate
orderDirectionstringOptionalOrder direction of feed items to return. Can be either asc or desc. Defaults to desc
Example#
- type: rss-feed  options:    rssUrl: https://www.schneier.com/blog/atom.xml    apiKey: xxxx
Info#
  • CORS: đŸŸĸ Enabled
  • Auth: 🟠 Optional
  • Price: 🟠 Free Plan (up to 10,000 requests / day)
  • Privacy: See Rss2Json Privacy Policy

Public IP#

Often find yourself searching "What's my IP", just so you can check your VPN is still connected? This widget displays your public IP address, along with ISP name and approx location. Data is fetched from IP-API.com.

Options#

No config options.

Example#
- type: public-ip
Info#
  • CORS: đŸŸĸ Enabled
  • Auth: 🟠 Optional
  • Price: đŸŸĸ Free
  • Host: Managed Instance Only
  • Privacy: See IP-API Privacy Policy

Crypto Watch List#

Keep track of price changes of your favorite crypto assets. Data is fetched from CoinGecko. All fields are optional.

Options#
FieldTypeRequiredDescription
assetsstringOptionalAn array of cryptocurrencies, coins and tokens. See list of supported assets. If none are specified, then the top coins by sortBy (defaults to market cap) will be returned
currencystringOptionalThe fiat currency to display price in, expressed as an ISO-4217 alpha code (see list of currencies). Defaults to USD
sortBystringOptionalThe method of sorting results. Can be marketCap, volume or alphabetical. Defaults to marketCap.
limitnumberOptionalNumber of results to return, useful when no assets are specified. Defaults to either all or 100
Example#
- type: crypto-watch-list  options:    limit: 10

Or

  - type: crypto-watch-list    options:      currency: GBP      sortBy: marketCap      assets:      - bitcoin      - ethereum      - monero      - cosmos      - polkadot      - dogecoin
Info#

Crypto Token Price History#

Shows recent price history for a given crypto asset, using price data fetched from CoinGecko

Options#
FieldTypeRequiredDescription
assetstringRequiredName of a crypto asset, coin or token to fetch price data for, see list of supported assets
currencystringOptionalThe fiat currency to display results in, expressed as an ISO-4217 alpha code (see list of currencies). Defaults to USD
numDaysnumberOptionalThe number of days of price history to render. Defaults to 7, min: 1, max: 30 days
chartColorstringOptionalColor of the chart value. Defaults to --widget-text-color which inherits dashboard primary color
chartHeightnumberOptionalThe height of rendered chart in px. Defaults to 300
Example#
- type: crypto-price-chart  options:    asset: bitcoin    currency: GBP    numDays: 7
Info#

Wallet Balance#

Keep track of your crypto balances and see recent transactions. Data is fetched from BlockCypher

Options#
FieldTypeRequiredDescription
coinstringRequiredSymbol of coin or asset, e.g. btc, eth or doge
addressstringRequiredAddress to monitor. This is your wallet's public / receiving address
networkstringOptionalTo use a different network, other than mainnet. Defaults to main
limitnumberOptionalLimit the number of transactions to display. Defaults to 10, set to large number to show all
Example#
- type: wallet-balance  options:    coin: btc    address: 3853bSxupMjvxEYfwGDGAaLZhTKxB2vEVC
Info#

Code Stats#

Display your coding summary. Code::Stats is a free and open source app that aggregates statistics about your programming activity. Dashy supports both the public instance, as well as self-hosted versions.

Options#
FieldTypeRequiredDescription
usernamestringRequiredYour CodeStats username
hostnamestringOptionalIf your self-hosting CodeStats, then supply the host name. By default it will use the public hosted instance
monthsToShownumberOptionalSpecify the number of months to render in the historical data chart. Defaults to 6
hideMetabooleanOptionalOptionally hide the meta section (username, level, all-time and recent XP)
hideHistorybooleanOptionalOptionally hide the historical calendar heat map
hideLanguagesbooleanOptionalOptionally hide the programming languages pie chart
hideMachinesbooleanOptionalOptionally hide the machines percentage chart
Example#
- type: code-stats  options:    username: alicia
Info#
  • CORS: đŸŸĸ Enabled
  • Auth: đŸŸĸ Not Required
  • Price: đŸŸĸ Free
  • Host: Self-Hosted or Managed
  • Privacy: See Code::Stats Privacy Policy

AnonAddy#

AnonAddy is a free and open source mail forwarding service. Use it to protect your real email address, by using a different alias for each of your online accounts, and have all emails land in your normal inbox(es). Supports custom domains, email replies, PGP-encryption, multiple recipients and more

This widget display email addresses / aliases from AnonAddy. Click an email address to copy to clipboard, or use the toggle switch to enable/ disable it. Shows usage stats (bandwidth, used aliases etc), as well as total messages recieved, blocked and sent. Works with both self-hosted and managed instances of AnonAddy.

Options#
FieldTypeRequiredDescription
apiKeystringRequiredYour AnonAddy API Key / Personal Access Token. You can generate this under Account Settings
hostnamestringOptionalIf your self-hosting AnonAddy, then supply the host name. By default it will use the public hosted instance
apiVersionstringOptionalIf you're using an API version that is not version v1, then specify it here
limitnumberOptionalLimit the number of emails shown per page. Defaults to 10
sortBystringOptionalSpecify the sort order for email addresses. Defaults to updated_at. Can be either: local_part, domain, email, emails_forwarded, emails_blocked, emails_replied, emails_sent, created_at, updated_at or deleted_at. Precede with a - character to reverse order.
searchTermstringOptionalA search term to filter results by, will search the email, description and domain
disableControlsbooleanOptionalPrevent any changes being made to account through the widget. User will not be able to enable or disable aliases through UI when this option is set
hideMetabooleanOptionalDon't show account meta info (forward/ block count, quota usage etc)
hideAliasesbooleanOptionalDon't show email address / alias list. Will only show account meta info
Example#
  - type: anonaddy    options:      apiKey: "xxxxxxxxxxxxxxxxxxxxxxxx\        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"      limit: 5      sortBy: created_at      disableControls: true
Info#
  • CORS: đŸŸĸ Enabled
  • Auth: 🔴 Required
  • Price: 🟠 Free for Self-Hosted / Free Plan available on managed instance or $1/month for premium
  • Host: Self-Hosted or Managed
  • Privacy: See AnonAddy Privacy Policy

Vulnerability Feed#

Keep track of recent security advisories and vulnerabilities, with optional filtering by score, exploits, vendor and product. All fields are optional.

Options#
FieldTypeRequiredDescription
sortBystringOptionalThe sorting method. Can be either publish-date, last-update or cve-code. Defaults to publish-date
limitnumberOptionalThe number of results to fetch. Can be between 5 and 30, defaults to 10
minScorenumberOptionalIf set, will only display results with a CVE score higher than the number specified. Can be a number between 0 and 9.9. By default, vulnerabilities of all CVE scores are shown
hasExploitbooleanOptionalIf set to true, will only show results with active exploits. Defaults to false
vendorIdnumberOptionalOnly show results from a specific vendor, specified by ID. See Vendor Search for list of vendors. E.g. 23 (Debian), 26 (Microsoft), 23682 (CloudFlare)
productIdnumberOptionalOnly show results from a specific app or product, specified by ID. See Product Search for list of products. E.g. 13534 (Docker), 15913 (NextCloud), 19294 (Portainer), 17908 (ProtonMail)
Example#
- type: cve-vulnerabilities

or

- type: cve-vulnerabilities  options:    sortBy: publish-date    productId: 28125    hasExploit: true    minScore: 5    limit: 30
Info#

Exchange Rates#

Display current FX rates in your native currency. Hover over a row to view more info, or click to show rates in that currency.

Options#
FieldTypeRequiredDescription
inputCurrencystringRequiredThe base currency to show results in. Specified as a 3-letter ISO-4217 code, see here for the full list of supported currencies, and their symbols
outputCurrenciesarrayRequiredList or currencies to show results for. Specified as a 3-letter ISO-4217 code, see here for the full list of supported currencies, and their symbols
apiKeystringRequiredAPI key for exchangerate-api.com, usually a 24-digit alpha-numeric string. You can sign up for a free account here
Example#
- type: exchange-rates  options:    apiKey: xxxxxxxxxxxxxxxxxxxxxxxx    inputCurrency: GBP    outputCurrencies:      - USD      - JPY      - HKD      - KPW
Info#
  • CORS: đŸŸĸ Enabled
  • Auth: 🔴 Required
  • Price: 🟠 Free plan (upto 100,000 requests/ month)
  • Host: Managed Instance Only
  • Privacy: See ExchangeRateAPI Privacy Policy

Public Holidays#

Counting down to the next day off work? This widget displays upcoming public holidays for your country. Data is fetched from Enrico

Options#
FieldTypeRequiredDescription
countrystringRequiredThe region to fetch holiday data for, specified as a country code, e.g. GB or US
holidayTypestringOptionalThe type of holidays to fetch. Can be: all, public_holiday, observance, school_holiday, other_day or extra_working_day. Defaults to public_holiday
monthsToShownumberOptionalThe number of months in advance to show. Min: 1, max: 24. Defaults to 12
Example#
- type: public-holidays  options:    country: GB    holidayType: all    monthsToShow: 12
Info#
  • CORS: đŸŸĸ Enabled
  • Auth: đŸŸĸ Not Required
  • Price: đŸŸĸ Free
  • Host: Self-Hosted (see jurajmajer/enrico) or Managed
  • Privacy: âšĢ No Policy Available

Covid-19 Status#

Keep track of the current COVID-19 status. Optionally also show cases by country, and a time-series chart. Uses live data from various sources, computed by disease.sh

Options#
FieldTypeRequiredDescription
showChartbooleanOptionalAlso display a time-series chart showing number of recent cases
showCountriesbooleanOptionalAlso display a list of cases per country
numDaysnumberOptionalSpecify number of days worth of history to render on the chart
countriesstring[]OptionalAn array of countries to display, specified by their ISO-3 codes. Leave blank to show all, sorted by most cases. showCountries must be set to true
limitnumberOptionalIf showing all countries, set a limit for number of results to return. Defaults to 10, no maximum
Example#
- type: covid-stats

Or

- type: covid-stats  options:    showChart: true    showCountries: true    countries:    - GBR    - USA    - IND    - RUS
Info#
  • CORS: đŸŸĸ Enabled
  • Auth: đŸŸĸ Not Required
  • Price: đŸŸĸ Free
  • Host: Managed Instance or Self-Hosted (see disease-sh/api)
  • Privacy: âšĢ No Policy Available
  • Conditions: Terms of Use

Sports Scores#

Show recent scores and upcoming matches from your favourite sports team. Data is fetched from TheSportsDB.com. From the UI, you can click any other team to view their scores and upcoming games, or click a league name to see all teams.

Options#
FieldTypeRequiredDescription
teamIdstringOptionalThe ID of a team to fetch scores from. You can search for your team on the Teams Page
leagueIdstringOptionalAlternatively, provide a league ID to fetch all games from. You can find the ID on the Leagues Page
pastOrFuturestringOptionalSet to past to show scores for recent games, or future to show upcoming games. Defaults to past. You can change this within the UI
apiKeystringOptionalOptionally specify your API key, which you can sign up for at TheSportsDB.com
limitnumberOptionalTo limit output to a certain number of matches, defaults to 15
Example#
- type: sports-scores  options:    teamId: 133636
Info#
  • CORS: đŸŸĸ Enabled
  • Auth: 🟠 Optional
  • Price: 🟠 Free plan (upto 30 requests / minute, limited endpoints)
  • Host: Managed Instance Only
  • Privacy: âšĢ No Policy Available

News Headlines#

Displays the latest news, click to read full article. Date is fetched from various news sources using Currents API

Options#
FieldTypeRequiredDescription
apiKeystringRequiredYour API key for CurrentsAPI. This is free, and you can get one here
countrystringOptionalFetch news only from a certain country or region. Specified as a country code, e.g. GB or US. See here for a list of supported regions
categorystringOptionalOnly return news from within a given category, e.g. sports, programming, world, science. The following categories are supported
langstringOptionalSpecify the language for returned articles as a 2-digit ISO code (limited article support). The following languages are supported, defaults to en
countnumberOptionalLimit the number of results. Can be between 1 and 200, defaults to 10
keywordsstringOptionalOnly return articles that contain an exact match within their title or description
hideImagesbooleanOptionalIf set to true, then article image thumbnails will not be displayed
Example#
- type: news-headlines    options:      apiKey: xxxxxxx      category: world
Info#
  • CORS: đŸŸĸ Enabled
  • Auth: 🔴 Required
  • Price: 🟠 Free plan (upto 600 requests / day)
  • Host: Managed Instance Only
  • Privacy: See CurrentsAPI Privacy Policy

TFL Status#

Shows real-time tube status of the London Underground. All fields are optional.

Options#
FieldTypeRequiredDescription
showAllbooleanOptionalBy default, details for lines with a Good Service are not visible, but you can click More Details to see all. Setting this option to true will show all lines on initial page load
sortAlphabeticallybooleanOptionalBy default lines are sorted by current status, set this option to true to instead sort them alphabetically
linesToShowarrayOptionalBy default all lines are shown. If you're only interested in the status of a few lines, then pass in an array of lines to show, specified by name
Example#
- type: tfl-status
  - type: tfl-status    options:      showAll: true      sortAlphabetically: true      linesToShow:      - District      - Jubilee      - Central
Info#
  • CORS: đŸŸĸ Enabled
  • Auth: đŸŸĸ Not Required
  • Price: đŸŸĸ Free
  • Host: Managed Instance Only
  • Privacy: See TFL Privacy Policy

Stock Price History#

Shows recent price history for a given publicly-traded stock or share

Options#
FieldTypeRequiredDescription
apiKeystringRequiredAPI key for Alpha Vantage, you can get a free API key here
stockstringRequiredThe stock symbol for the asset to fetch data for
priceTimestringOptionalThe time to fetch price for. Can be high, low, open or close. Defaults to high
chartColorstringOptionalColor of the chart value. Defaults to --widget-text-color which inherits dashboard primary color
chartHeightnumberOptionalThe height of rendered chart in px. Defaults to 300
Example#
- type: stock-price-chart  options:    stock: NET    apiKey: PGUWSWD6CZTXMT8N
Info#
  • CORS: đŸŸĸ Enabled
  • Auth: 🔴 Required
  • Price: 🟠 Free plan (upto 500 requests/day)
  • Host: Managed Instance Only
  • Privacy: See AlphaVantage Privacy Policy

ETH Gas Prices#

Renders the current Gas cost of transactions on the Ethereum network (in both GWEI and USD), along with recent historical prices. Useful for spotting a good time to transact. Uses data from ethgas.watch

Options#

No config options.

Example#
- type: eth-gas-prices
Info#
  • CORS: đŸŸĸ Enabled
  • Auth: đŸŸĸ Not Required
  • Price: đŸŸĸ Free
  • Host: Managed Instance or Self-Hosted (see wslyvh/ethgaswatch)
  • Privacy: âšĢ No Policy Available

Joke#

Renders a programming or generic joke. Data is fetched from the JokesAPI by @Sv443. All fields are optional.

Options#
FieldTypeRequiredDescription
categorystringOptionalSet the category of jokes to return. Use a string to specify a single category, or an array to pass in multiple options. Available options are: all, programming, pun, dark, spooky, christmas and misc. An up-to-date list of supported categories can be found here. Defaults to all
safeModebooleanOptionalSet to true, to prevent the fetching of any NSFW jokes. Defaults to false
languagestringOptionalSpecify the language for returned jokes. The following languages are supported: en, cs, de, es, fr and pt, and an up-to-date list of supported languages can be found here. By default, your system language will be used, if it's supported, otherwise English
Example#
- type: joke  options:    safeMode: true    language: en    category: Programming
Info#

XKCD Comics#

Have a laugh with the daily comic from XKCD. A classic webcomic website covering everything from Linux, math, romance, science and language. All fields are optional.

Options#
FieldTypeRequiredDescription
comicstring / numberOptionalChoose which comic to display. Set to either random, latest or the series number of a specific comic, like 627. Defaults to latest
Example#
- type: xkcd-comic  options:    comic: latest
Info#
  • CORS: đŸŸĸ Enabled
  • Auth: đŸŸĸ Not Required
  • Price: đŸŸĸ Free
  • Privacy: âšĢ No Policy Available

Flight Data#

Displays airport departure and arrival flights, using data from AeroDataBox. Useful if you live near an airport and often wonder where the flight overhead is going to. Hover over a row for more flight data.

Options#
FieldTypeRequiredDescription
airportstringRequiredThe airport to show flight data from. Should be specified as a 4-character ICAO-code, a full list of which can be found here (example: KBJC or EGKK)
apiKeystringRequiredA valid RapidAPI Key, with AeroDataBox enabled (check in your Subscription Dashboard). This API is free to sign up for and use
limitnumberOptionalFor busy airports, you may wish to limit the number of results visible
directionstringOptionalBy default, both departure and arrival flights will be fetched, if you would like to only show flights in one direction, set this to wither departure or arrival
Example#
- type: flight-data  options:    airport: EGLC    apiKey: XXXXX    limit: 12    direction: all
Info#
  • CORS: đŸŸĸ Enabled
  • Auth: 🔴 Required
  • Price: 🟠 Free plan (upto 150 requests / month)
  • Host: Managed Instance Only
  • Privacy: See AeroDataBox and RapidAPI Policy

Astronomy Picture of the Day#

Show the NASA Astronomy Pictore of the Day. Data is fetched from APOD using PawelPleskaczynski/apod_api.

Options#

No config options.

Example#
- type: apod
Info#

GitHub Trending#

Displays currently trending projects on GitHub. Optionally specify a language and time-frame. Data is fetched from Lissy93/gh-trending-no-cors using the GitHub API. All fields are optional.

Options#
FieldTypeRequiredDescription
langstringOptionalA programming language to fetch trending repos from that category. E.g. javascript or go
sincestringOptionalThe timeframe to use when calculating trends. Can be either daily, weekly or monthly. Defaults to daily
limitnumberOptionalOptionally limit the number of results. Max 25, default is 10
Example#
- type: github-trending-repos  options:    limit: 8    since: weekly
Info#

GitHub Profile Stats#

Display stats from your GitHub profile, using embedded cards from anuraghazra/github-readme-stats

Options#
FieldTypeRequiredDescription
usernamestringRequiredThe GitHub username to fetch info for. E.g. lissy93. (Not required if hideProfileCard and hideLanguagesCard are both set to true)
hideProfileCardbooleanOptionalIf set to true, the users profile card will not be shown. Defaults to false
hideLanguagesCardbooleanOptionalIf set to true, the users top languages card will not be shown. Defaults to false
reposarrayOptionalIf you'd like to also display stats for some GitHub reposotories, then add an array or repo names here. Specified as [username]/[repo-name], e.g. lissy93/dashy
Example#
- type: github-profile-stats  options:    username: Lissy93    hideLanguagesCard: true    repos:    - lissy93/dashy    - lissy93/personal-security-checklist    - lissy93/twitter-sentiment-visualisation
Info#

Self-Hosted Services Widgets#

System Info#

Displays info about the server which Dashy is hosted on. Includes user + host, operating system, uptime and basic memory & load data.

Options#

No config options.

Example#
- type: system-info
Info#

No external data requests made

Cron Monitoring (Health Checks)#

Cron job monitoring using Health Checks. Both managed and self-hosted instances are supported.

Options#
FieldTypeRequiredDescription
apiKeystringRequiredA read-only API key for the project to monitor. You can generate this by selecting a Project --> Settings --> API Access. Note that you must generate a separate key for each project
hoststringOptionalIf you're self-hosting, or using any instance other than the official (healthchecks.io), you will need to specify the host address. E.g. https://healthchecks.example.com or http://cron-monitoing.local
Example#
- type: health-checks  options:    apiKey: XXXXXXXXX
Info#

CPU History (NetData)#

Pull recent CPU usage history from NetData.

Options#
FieldTypeRequiredDescription
hoststringRequiredThe URL to your NetData instance
chartHeightnumberOptionalThe height of rendered chart in px. Defaults to 300
chartColor / chartColorsstring / arrayOptionalColor of the chart value(s) as hex codes. chartColor is a single value (defaults to --widget-text-color), whereas chartColors is an array of colors
Example#
- type: nd-cpu-history  options:  host: http://192.168.1.1:19999
Info#

Memory History (NetData)#

Pull recent system RAM usage from NetData, and show as a breakdown of different categories.

Options#
FieldTypeRequiredDescription
hoststringRequiredThe URL to your NetData instance
chartHeightnumberOptionalThe height of rendered chart in px. Defaults to 300
chartColor / chartColorsstring / arrayOptionalColor of the chart value(s) as hex codes. chartColor is a single value (defaults to --widget-text-color), whereas chartColors is an array of colors
Example#
- type: nd-ram-history  options:    host: http://192.168.1.1:19999
Info#

Load History (NetData)#

Pull recent load usage in 1, 5 and 15 minute intervals, from NetData.

Options#
FieldTypeRequiredDescription
hoststringRequiredThe URL to your NetData instance
chartHeightnumberOptionalThe height of rendered chart in px. Defaults to 300
chartColor / chartColorsstring / arrayOptionalColor of the chart value(s) as hex codes. chartColor is a single value (defaults to --widget-text-color), whereas chartColors is an array of colors
Example#
- type: nd-load-history  options:  host: http://192.168.1.1:19999
Info#

Pi Hole Stats#

Displays the number of queries blocked by Pi-Hole.

Options#
FieldTypeRequiredDescription
hostnamestringRequiredThe URL to your Pi-Hole instance
hideStatus / hideChart / hideInfobooleanOptionalOptionally hide any of the three parts of the widget
Example#
- type: pi-hole-stats  options:    hostname: http://192.168.130.1
Info#

Pi Hole Queries#

Shows top queries that were blocked and allowed by Pi-Hole.

Options#
FieldTypeRequiredDescription
hostnamestringRequiredThe URL to your Pi-Hole instance
apiKeystringRequiredYour Pi-Hole web password. It is NOT your pi-hole admin interface or server password. It can be found in /etc/pihole/setupVars.conf, and is a 64-character located on the line that starts with WEBPASSWORD
countnumberOptionalThe number of queries to display. Defaults to 10
Example#
- type: pi-hole-top-queries  options:    hostname: https://pi-hole.local    apiKey: xxxxxxxxxxxxxxxxxxxxxxx
Info#

Recent Traffic#

Shows number of recent traffic, using allowed and blocked queries from Pi-Hole

Options#
FieldTypeRequiredDescription
hostnamestringRequiredThe URL to your Pi-Hole instance
Example#
- type: pi-hole-traffic  options:    hostname: https://pi-hole.local
Info#

Stat Ping Statuses#

Displays the current and recent uptime of your running services, via a self-hosted instance of StatPing

Options#
FieldTypeRequiredDescription
hostnamestringRequiredThe URL to your StatPing instance, without a trailing slash
Example#
- type: stat-ping  options:    hostname: http://192.168.130.1:8080
Info#

System Resource Monitoring#

The easiest method for displaying system info and resource usage in Dashy is with Glances.

Glances is a cross-platform monitoring tool developed by @nicolargo. It's similar to top/htop but with a Rest API and many data exporters available. Under the hood, it uses psutil for retrieving system info.

If you don't already have it installed, either follow the Installation Guide for your system, or setup with Docker, or use the one-line install script: curl -L https://bit.ly/glances | /bin/bash.

Glances can be launched with the glances command. You'll need to run it in web server mode, using the -w option for the API to be reachable. If you don't plan on using the Web UI, then you can disable it using --disable-webui. See the command reference docs for more info.

Options#

All Glance's based widgets require a hostname. All other parameters are optional.

FieldTypeRequiredDescription
hostnamestringRequiredThe URL or IP + port to your Glances instance (without a trailing slash)
usernamestringOptionalIf you have setup basic auth on Glances, specify username here (defaults to glances)
passwordstringOptionalIf you have setup basic auth on Glances, specify password here. Note: since this password is in plaintext, it is important not to reuse it anywhere else
apiVersionstringOptionalSpecify an API version, defaults to V 3. Note that support for older versions is limited
limitnumberOptionalFor widgets that show a time-series chart, optionally limit the number of data points returned. A higher number will show more historical results, but will take longer to load. A value between 300 - 800 is usually optimal
Info#
  • CORS: đŸŸĸ Enabled
  • Auth: 🟠 Optional
  • Price: đŸŸĸ Free
  • Host: Self-Hosted (see GitHub - Nicolargo/Glances)
  • Privacy: âšĢ No Policy Available
Screenshot#

example-screenshot

Current CPU Usage#

Live-updating current CPU usage, as a combined average across alll cores

Example#
- type: gl-current-cpu  options:    hostname: http://192.168.130.2:61208

CPU Usage Per Core#

Live-updating CPU usage breakdown per core

Example#
- type: gl-current-cores  options:    hostname: http://192.168.130.2:61208

CPU Usage History#

Recent CPU usage history, across all cores, and displayed by user and system

Options#
FieldTypeRequiredDescription
limitnumberOptionalLimit the number of results returned, rendering more data points will take longer to load. Defaults to 100
Example#
- type: gl-cpu-history  options:    hostname: http://192.168.130.2:61208    limit: 60

Current Memory Usage#

Real-time memory usage gauge, with more info visible on click

Example#
- type: gl-current-mem  options:    hostname: http://192.168.130.2:61208

Memory Usage History#

Recent memory usage chart

Options#
FieldTypeRequiredDescription
limitnumberOptionalLimit the number of results returned, rendering more data points will take longer to load. Defaults to 100
Example#
- type: gl-mem-history  options:    hostname: http://localhost:61208    limit: 80

Disk Space#

List connected disks, showing free / used space and other info (file system, mount point and space available)

Example#
- type: gl-disk-space  options:    hostname: http://192.168.130.2:61208

Disk IO#

Shows real-time read and write speeds and operations per sec for each disk

Example#
- type: gl-disk-io  options:    hostname: http://192.168.130.2:61208

System Load#

Shows the number of processes waiting in the run-queue, averaged across all cores. Displays for past 5, 10 and 15 minutes

Example#
- type: gl-system-load  options:    hostname: http://192.168.130.2:61208

System Load History#

Shows recent historical system load, calculated from the number of processes waiting in the run-queue, in 1, 5 and 15 minute intervals, and averaged across all cores. Optionally specify limit to set number of results returned, defaults to 500, max 100000, but the higher the number the longer the load and render times will be.

Example#
- type: gl-load-history  options:    hostname: http://192.168.130.2:61208

Network Interfaces#

Lists visible network interfaces, including real-time upload/ download stats

Example#
- type: gl-network-interfaces  options:    hostname: http://192.168.130.2:61208

Network Traffic#

Shows amount of data recently uploaded/ downloaded across all network interfaces. Optionally set the limit option to specify number historical of data points to return

Example#
- type: gl-network-traffic  options:    hostname: http://192.168.130.2:61208    limit: 500

Resource Usage Alerts#

Lists recent high resource usage alerts (e.g. CPU, mem, IO, load, temp)

Example#
- type: gl-alerts  options:    hostname: http://192.168.130.2:61208

Dynamic Widgets#

Iframe Widget#

Embed any webpage into your dashboard as a widget.

Options#
FieldTypeRequiredDescription
urlstringRequiredThe URL to the webpage to embed
frameHeightnumberOptionalIf needed, specify height of iframe in px. E.g. 400, defaults to auto
Example#
- type: iframe  options:    url: https://fiatleak.com/

HTML Embedded Widget#

Many websites and apps provide their own embeddable widgets. These can be used with Dashy using the Embed widget, which lets you dynamically embed and HTML, CSS or JavaScript contents.

⚠ī¸ NOTE: Use with extreme caution. Embedding a script from an untrustworthy source may have serious unintended consequences.

Options#
FieldTypeRequiredDescription
htmlstringOptionalHTML contents to render in the widget
scriptstringOptionalRaw JavaScript code to execute (caution)
scriptSrcstringOptionalA URL to JavaScript content (caution)
cssstringOptionalAny stylings for widget contents
Example#
- type: embed  options:    scriptSrc: https://cdn.speedcheck.org/basic/scbjs.min.js    html: |       <div id="sc-container">      <div id="sc-branding" class="sc-bb">      <a target="_blank" href="https://www.speedcheck.org/">      <img src="https://cdn.speedcheck.org/branding/speedcheck-logo-18.png" alt="Speedcheck"/>      </a>      </div>      </div>

Or

- type: embed    options:      css: '.coinmarketcap-currency-widget { color: var(--widget-text-color); }'      html: '<div class="coinmarketcap-currency-widget" data-currencyid="1" data-base="USD" data-secondary="" data-ticker="true" data-rank="true" data-marketcap="true" data-volume="true" data-statsticker="true" data-stats="USD"></div>'      scriptSrc: 'https://files.coinmarketcap.com/static/widget/currency.js'

API Response#

Directly output plain-text response from any API-enabled service.

// Coming soon...

Prometheus Data#

Display data from any service with a Prometheus exporter.

// Coming soon...

Data Feed#

Show live data from an RSS-enabled service. The only required parameter is rssUrl, which is the URL to the ATOM feed. See RSS Widget for full list of available options.

Example#
- type: rss-feed  options:    rssUrl: https://notes.aliciasykes.com/feed

Usage & Customizations#

Widget Usage Guide#

Like items, widgets are placed under sections. You may have one or more widgets per section.

In your YAML config file, this will look something like:

sections:- name: Today  icon: far fa-calendar-day  widgets:  - type: clock    options:      format: en-GB  - type: weather    options:      apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx      city: London      units: metric

In this example, there is a single section, named "Today", using a Calendar icon from Font-Awesome. It has 2 widgets, a clock and the current weather.

Continuous Updates#

By default, a widget which displays dynamic data from an external source, will only fetch results on page load. If you would like to keep data updated at all times, you can enable Continuous Updates. This is done by setting a time value in the updateInterval field.

The value of updateInterval is optional, and is specified and seconds. It must be more than 10 and less than 7200.

For example, the following widget displaying stats from Pi-Hole will update ever 20 seconds.

widgets:- type: pi-hole-stats  updateInterval: 20  options:    hostname: http://192.168.130.2

Note that if you have many widgets, and set them to continuously update frequently, you will notice a hit to performance. A widget that relies on data from an external API, will also consume your usage quota faster, if set to keep updating.

Proxying Requests#

If a widget fails to make a data request, and the console shows a CORS error, this means the server is blocking client-side requests.

Dashy has a built-in CORS proxy (services/cors-proxy.js), which will be used automatically by some widgets, or can be forced to use by other by setting the useProxy option.

For example:

widgets:- type: pi-hole-stats  useProxy: true  options:    hostname: http://pi-hole.local

Alternativley, and more securley, you can set the auth headers on your service to accept requests from Dashy. For example:

Access-Control-Allow-Origin: https://location-of-dashy/Vary: Origin

Widget Styling#

Like elsewhere in Dashy, all colours can be easily modified with CSS variables.

Widgets use the following color variables, which can be overridden if desired:

  • --widget-text-color - Text color, defaults to --primary
  • --widget-background-color - Background color, defaults to --background-darker
  • --widget-accent-color - Accent color, defaults to --background

For more info on how to apply custom variables, see the Theming Docs

Customizing Charts#

For widgets that contain charts, you can set an array of colors under chartColors. To specify the chart height, set chartHeight to an integer (in px), defaults to 300. For example:

- type: gl-load-history  options:    hostname: http://192.168.130.2:61208    chartColors: ['#9b5de5', '#f15bb5', '#00bbf9', '#00f5d4']    chartHeight: 450

Language Translations#

Since most of the content displayed within widgets is fetched from an external API, unless that API supports multiple languages, translating dynamic content is not possible.

However, any hard-coded content is translatable, and all dates and times will display in your local format.

For more info about multi-language support, see the Internationalization Docs.

Widget UI Options#

Widgets can be opened in full-page view, by clicking the Arrow icon (top-right). The URL in your address bar will also update, and visiting that web address directly will take you straight to that widget.

You can reload the data of any widget, by clicking the Refresh Data icon (also in top-right). This will only affect the widget where the action was triggered from.

All config options that can be applied to sections, can also be applied to widget sections. For example, to make a widget section double the width, set displayData.cols: 2 within the parent section. You can collapse a widget (by clicking the section title), and collapse state will be saved locally.

Widgets cannot currently be edited through the UI. This feature is in development, and will be released soon. In the meantime, you can either use the JSON config editor, or use VS Code Server, or just SSH into your box and edit the conf.yml file directly.

Build your own Widget#

Widgets are built in a modular fashion, making it easy for anyone to create their own custom components.

For a full tutorial on creating your own widget, you can follow this guide, or take a look at here for a code example.

Alternatively, for displaying simple data, you could also just use the either the iframe, embed, data feed or API response widgets.

Requesting a Widget#

Suggestions for widget ideas are welcome. But there is no guarantee that I will build your widget idea.

You can suggest a widget here, please star the repo before submitting a ticket.

Please only request widgets for services that:

  • Have a publicly accessible API
  • Are CORS and HTTPS enabled
  • Are free to use, or have a free plan
  • Allow for use in their Terms of Service
  • Would be useful for other users

For services that are not officially supported, it is likely still possible to display data using either the iframe, embed or API response widgets. For more advanced features, like charts and action buttons, you could also build your own widget, using this tutorial, it's fairly straight forward, and you can use an existing widget (or this example) as a template.