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.

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
hideSecondsbooleanOptionalIf set to true, seconds will not be shown. Defaults to false
use12HourbooleanOptionalIf set to true, 12 hour time will be displayed. Defaults to the settings suggested by the current format and timeZone

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
cityIdnumberOptionalAn OpenWeatherMap numeric city ID, used to disambiguate cities that share a name. You can find the ID in the URL of the city's page on openweathermap.org (e.g. 2643743 for London, GB). If provided, this will override the city option
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
latnumberOptionalTo show weather for a specific location, you can provide the latitude and longitude coordinates. If provided, this will override the city and cityId options
lonnumberOptionalTo show weather for a specific location, you can provide the latitude and longitude coordinates. If provided, this will override the city and cityId options

Example​

- type: weather
  options:
    apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    city: London
    units: metric
    hideDetails: true

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
cityIdnumberOptionalAn OpenWeatherMap numeric city ID, used to disambiguate cities that share a name. You can find the ID in the URL of the city's page on openweathermap.org (e.g. 2643743 for London, GB). If provided, this will override the city option
latnumberOptionalLatitude for a specific location. If provided alongside lon, this will override the city and cityId options
lonnumberOptionalLongitude for a specific location. If provided alongside lat, this will override the city and cityId options
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
parseLocallybooleanOptionalIf true parse the rss feed locally instead of using the rss2json API.

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

Image​

Displays an image.

This may be useful if you have a service (such as Grafana - see example), which periodically exports charts or other data as an image.

You can also store images within Dashy's public directory (using a Docker volume), and reference them directly. E.g. -v ./path/to/my-homelab-logo.png:/app/public/logo.png, then in the widget imagePath: /logo.png.

Similarly, any web service that serves up widgets as image can be used. E.g. you could show current star chart for a GitHub repo, with: imagePath: https://starchart.cc/Lissy93/dashy.svg.

If you'd like to embed a live screenshot, of all or just part of a website, then this can be done using API Flash.

Or what about showing a photo of the day? Try https://source.unsplash.com/random/400x300 or https://picsum.photos/400/300

Options​

FieldTypeRequiredDescription
imagePathstringRequiredThe path (local or remote) of the image to display
imageWidthstringOptionalSpecify a fixed width for rendered image. Accepts either integer value in px, or any string value with units (e.g. 420, 100px, 6.9rem) (defaults to auto)
imageHeightstringOptionalSpecify a fixed height for rendered image. Accepts either integer value in px, or any string value with units (e.g. 420, 100px, 6.9rem) (defaults to auto)

Example​

- type: image
  options:
    imagePath: https://i.ibb.co/yhbt6CY/dashy.png

Info​

Unless image fetched from remote source, no external data request is made.

Public IP​

Displays your public IP address, ISP and approximate location.

Options​

FieldTypeRequiredDescription
providerstringOptionalOne of ipinfo (default), freeipapi, ipquery, ip-api, or ipgeolocation. See the table below
apiKeystringOptionalRequired for ipgeolocation. Optional for ipinfo (a free token raises the rate limit from ~1k/day to ~50k/month)
hideLocationbooleanOptionalSet to true to hide the flag, ISP name and city/region — only the IP address is shown. Defaults to false

Example​

Default (no options needed)

- type: public-ip

Using ip-api via the proxy (gets server IP, because of useProxy)

- type: public-ip
  useProxy: true
  options:
    provider: ip-api

Using ipgeolocation with a key:

- type: public-ip
  options:
    provider: ipgeolocation
    apiKey: xxxxxxxxxxxxxxx
tip

Setting useProxy: true makes the lookup happen from Dashy's server instead of your browser, so the upstream API returns the public IP of the machine running Dashy, whereas without useProxy it will show your public IP.

Supported providers​

ProviderKeyProxyNotes
ipinfo (default)🟢 Not needed / 🟠 Optional🟢 Not neededService from ipinfo.io. Keyless gives ~1k/day; a free token raises this to ~50k/month. Sometimes blocked by adblockers.
freeipapi🟢 Not needed🟢 Not neededKeyless, 60 req/min via freeipapi.com.
ipquery🟢 Not needed🟢 Not neededModern keyless API from ipquery.io. Includes VPN/Tor/datacenter risk flags in the raw response.
ip-api🟢 Not needed🔴 Requiredip-api.com is HTTP-only on the free tier, so the proxy is needed to avoid mixed-content errors.
ipgeolocation🔴 Required🟢 Not neededGet a free key from ipgeolocation.io.

Info​

  • CORS: 🟢 Enabled (only provider: ip-api needs the proxy)
  • Auth: 🟠 Optional (only ipgeolocation requires a key, and ipinfo is optional)
  • Price: 🟢 Free
  • Host: Managed Instance Only
  • Privacy: See the policy for whichever provider you choose: freeipapi.com, ipinfo.io, ipquery.io, ip-api.com, IPGeoLocation.

IP Blacklist​

Notice certain web pages aren't loading? This widget quickly shows which blacklists your IP address (or host, or email) appears on, using data from blacklistchecker.com.

Options​

FieldTypeRequiredDescription
ipAddressstringOptionalThe IP to check. This can also be a domain/ host name or even an email address. If left blank, Dashy will use your current public IP address.
apiKeystringRequiredYou can get your free API key from blacklistchecker.com

Example​

- type: blacklist-check
  options:
    apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    ipAddress: 1.1.1.1

Info​

Domain Monitor​

Keep an eye on the expiry dates of your domain names, using public whois records fetched from whoapi.com. Click the domain name to view additional info, like registrar, name servers and date last updated.

Options​

FieldTypeRequiredDescription
domainstringRequiredThe domain to check
apiKeystringRequiredGet your API key from my.whoapi.com, requires a paid plan
showFullInfobooleanOptionalIf set to true, the toggle-full-info panel will be open by default

Example​

  - type: domain-monitor
    options:
      domain: example.com
      apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

  - type: domain-monitor
    options:
      domain: example2.com
      apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Info​

  • CORS: 🟢 Enabled
  • Auth: 🔴 Required
  • Price: 🔴 Paid only, no free plan
  • Host: Managed Instance Only
  • Privacy: See WhoAPI 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

Mullvad Status​

Shows your Mullvad VPN connection status, as well as server info. Fetched from am.i.mullvad.net

Options​

No Options.

Example​

- type: mullvad-status

Info​

  • CORS: 🟢 Enabled
  • Auth: 🟢 Not Required
  • Price: 🟢 Free
  • Host: Managed
  • Privacy: See Mullvad Privacy Policy

addy.io​

addy.io 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 addy.io. 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 received, blocked and sent. Works with both self-hosted and managed instances of addy.io.

Options​

FieldTypeRequiredDescription
apiKeystringRequiredYour addy.io API Key / Personal Access Token. You can generate this under API Settings
hostnamestringOptionalIf your self-hosting addy.io, 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: addy
    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 addy.io Privacy Policy

Vulnerability Feed​

Keep track of recent security advisories and vulnerabilities, with optional filtering by score, exploits, vendor and product. Using data from NIST Vulnerability API. All fields are optional.

Options​

FieldTypeRequiredDescription
cveTagstringOptionalThis parameter returns only the CVE records that include the provided cveTag. Options are disputed, unsupported-when-assigned or exclusively-hosted-service
limitnumberOptionalThe number of results to fetch. Can be between 5 and 30, defaults to 5
cvssV2SeveritystringOptionalThis parameter returns only the CVEs that match the provided CVSSv2 qualitative severity rating. Options are LOW, MEDIUM, HIGH or CRITICAL
cvssV3SeveritystringOptionalThis parameter returns only the CVEs that match the provided CVSSv3 qualitative severity rating. Options are LOW, MEDIUM, HIGH or CRITICAL
cvssV4SeveritystringOptionalThis parameter returns only the CVEs that match the provided CVSSv4 qualitative severity rating. Options are LOW, MEDIUM, HIGH or CRITICAL
keywordSearchstringOptionalThis parameter returns only the CVEs where a word or phrase is found in the current description
apiKeystringOptionalWithout a key you're limited to 5 requests every 30 seconds. You can get a free API key from here

Example​

- type: cve-vulnerabilities

or

- type: cve-vulnerabilities
  options:
    cveTag: disputed
    cvssV2Severity: CRITICAL
    limit: 30

Info​

  • CORS: 🟠 Proxied
  • Auth: 🟢 Not Required (free apiKey recommended for multiple widgets)
  • Price: 🟢 Free
  • Host: Managed
  • Privacy: See CVE Details Privacy Policy

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 (up to 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

Note, config for this widget is case-sensitive (see #1268)

Options​

FieldTypeRequiredDescription
countrystringRequiredThe country to fetch holiday data for, specified as a country code, e.g. GB or US
statestringOptionalrestrict a country to a specific state defined by ISO_3166-2, e.g. LND.
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
langstringOptionalThe language in which the events should be. Usually local languages and english are available. Default to first available in the country. e.g. en or fr.

Example​

- type: public-holidays
  options:
    country: GB
    state: LND
    holidayType: all
    monthsToShow: 12
    lang: en

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 favorite 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
hideImagebooleanOptionalSet to true to not render the team / match banner image, defaults to false

Example​

- type: sports-scores
  options:
    teamId: 133636

Info​

  • CORS: 🟢 Enabled
  • Auth: 🟠 Optional
  • Price: 🟠 Free plan (up to 30 requests / minute, limited endpoints)
  • Host: Managed Instance Only
  • Privacy: ⚫ No Policy Available

Live Tennis​

Live tennis scores from the ATP and WTA tours, updating in place. Each match shows both players with their per-set game scores, the current game points, and a marker against whoever is serving. Set the status option to show upcoming or recently finished matches instead. Data is from LiveTennisAPI.

Options​

FieldTypeRequiredDescription
apiKeystringRequiredYour LiveTennisAPI key. The free plan needs no card, and is enough for this widget
statusstringOptionalWhich matches to show: live, upcoming or completed. Defaults to live
limitnumberOptionalMaximum number of matches to show, defaults to 5
hideRankingsbooleanOptionalSet to true to hide each player's world ranking, defaults to false
hideTournamentbooleanOptionalSet to true to hide the tournament name, defaults to false

Example​

- type: live-tennis
  options:
    apiKey: twjp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    limit: 5

Showing the next matches due on court, instead of those in play:

- type: live-tennis
  options:
    apiKey: twjp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    status: upcoming
    hideRankings: true

Info​

  • CORS: 🟢 Enabled (no proxy needed)
  • Auth: 🔴 Required
  • Price: 🟠 Free plan (30 requests / minute)
  • Host: Managed Instance Only
  • Privacy: LiveTennisAPI Privacy Policy

The widget refreshes every 60 seconds by default, which sits comfortably inside the free plan's rate limit. You can change this with the standard updateInterval option, but note that several widgets sharing one key all count against the same limit.

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 (up to 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 (up to 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​

Chuck Norris quotes​

Renders a Chuck Norris quote. Data is fetched from the ChuckNorrisAPI by @matchilling. All fields are optional.

Options​

FieldTypeRequiredDescription
categoriesstringOptionalSet 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: animal,career,celebrity,dev,explicit,fashion,food,history,money,movie,music,political,religion,science,sport and travel. An up-to-date list of supported categories can be found here. Defaults to not explicitely set and therefore any of the categories can come up.

Example​

- type: chucknorris
  options:
    categories: history,sport

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 (up to 150 requests / month)
  • Host: Managed Instance Only
  • Privacy: See AeroDataBox and RapidAPI Policy

Astronomy Picture of the Day​

Show the NASA Astronomy Picture of the Day. Data is fetched from APOD using @Lissy93/go-apod / hosted at apod.as93.net.

Options​

No config options.

Example​

- type: apod

Info​

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​

Shows GitHub user stats (if username) and repos stats (for each repo in repos). Fetched from the GitHub API.

Options​

FieldTypeRequiredDescription
usernamestringOptionalA GitHub username, e.g. lissy93. If this is set, a profile card is shown, if it's unset the card isn't shown
reposarrayOptionalA list of repositories to show stats for, each specified as [owner]/[repo], e.g. lissy93/dashy
tokenstringOptionalAn optional GitHub token. Used to raise the API rate limit from 60 to 5,000 requests per hour (can be set directly, or as an environment variable)

Example​

- type: github-profile-stats
  options:
    username: lissy93
    repos:
    - lissy93/dashy
    - lissy93/portainer-templates
    - lissy93/web-check

Or just show the user's profile card:

- type: github-profile-stats
  options:
    username: octocat

Or just show repo(s)

- type: github-profile-stats
  options:
    repos:
    - lissy93/dashy

Info​

HealthChecks Status​

Display cron job monitor status of one or more HealthChecks project(s). Works with healthchecks.io and your selfhosted instance.

Options​

FieldTypeRequiredDescription
hoststringOptionalThe base url of your instance, default is https://healthchecks.io
apiKeystring (or string[] for multiple)RequiredAPI key(s) for project(s) to monitor. Generate a separate key per project (read-only is fine), under Project --> Settings --> API Access
Example​
- type: health-checks
  options:
    host: https://healthcheck.your-domain.de
    apiKey: 
      - abcdefg...
      - zxywvu...

Or, a single project:

      - type: health-checks
        options:
          host: https://healthchecks.io
          apiKey: hcw_xxxxxxxxxxxxxxxxxxxxxxxx

Info​

Display new and trending Posts from Hackernews

Options​

FieldTypeRequiredDescription
storiesstringOptionalHN Stories to display defaults to topstories. Options are: beststories, topstories or newstories
limitintOptionalThe size of the list of Posts to show.
Example​
- type: hackernews-trending
  options:
    stories: newstories
    limit: 10

MVG Departure​

Display departure time of a MVG (Münchner Verkehrs Gesellschaft) station.

From https://www.mvg.de/impressum.html:

[...] Die Verarbeitung unserer Inhalte oder Daten durch Dritte erfordert unsere ausdrückliche Zustimmung. Für private, nicht-kommerzielle Zwecke, wird eine gemäßigte Nutzung ohne unsere ausdrückliche Zustimmung geduldet. Jegliche Form von Data-Mining stellt keine gemäßigte Nutzung dar.[...]

In other words: Private, noncomercial, moderate use of the API is tolerated. They don’t consider data mining as moderate use. (This is not a legal advice)

Options​

FieldTypeRequiredDescription
locationstringRequiredThe name of the location (exact) or the location id, startin with de:09162:
limitintegerOptionalLimit number of entries, defaults to 10.
titlestringOptionalA custom title to be displayed.
headerboolOptionalShall the title be shown?
filtersobjectOptionalFilter results
filters.linestring/arrayOptionalFilter results for given line(s).
filters.productstring/arrayOptionalFilter results for specific product (TRAM, UBAHN, SBAHN, BUS).
filters.destinationstring/objectOptionalFilter results for specific destination(s)
- type: mvg
  options:
    location: Marienplatz
    limit: 5

Info​

  • CORS: 🟢 Enabled
  • Auth: 🟢 Not Required
  • Price: 🟢 Free / Private use only
  • Host: MVG
  • Privacy: See MVG Datenschutz

MVG Connection​

Display the next connection for two addresses/coordinates, stations or POI within Munich using MVG MVG (Münchner Verkehrs Gesellschaft).

From https://www.mvg.de/impressum.html:

[...] Die Verarbeitung unserer Inhalte oder Daten durch Dritte erfordert unsere ausdrückliche Zustimmung. Für private, nicht-kommerzielle Zwecke, wird eine gemäßigte Nutzung ohne unsere ausdrückliche Zustimmung geduldet. Jegliche Form von Data-Mining stellt keine gemäßigte Nutzung dar.[...]

In other words: Private, noncomercial, moderate use of the API is tolerated. They don’t consider data mining as moderate use. (This is not a legal advice)

Options​

FieldTypeRequiredDescription
originstringRequiredOrigin of the connection.
destinationstringRequiredDestination of the connection.
titlestringOptionalA custom title to be displayed.
headerboolOptionalShall the title be shown?
filtersobjectOptionalFilter results
filters.linestring/arrayOptionalFilter results for given line(s).
filters.productstring/arrayOptionalFilter results for specific product (TRAM, UBAHN, SBAHN, BUS).
filters.destinationstring/objectOptionalFilter results for specific destination(s)
- type: mvg-connection
  options:
    from: Marienplatz
    from: Dachauer Straße 123
    header: true
    filters:
      product: [UBAHN]
      line: [U1,U2,U4,U5]

Info​

  • CORS: 🟢 Enabled
  • Auth: 🟢 Not Required
  • Price: 🟢 Free / Private use only
  • Host: MVG
  • Privacy: See MVG Datenschutz

Custom List​

Renders custom schema-compliant JOSN in a list.

Options​

FieldTypeRequiredDescription
urltextRequiredA string containing the url of a json file.
titletextoptionalA title for the widget. Can be helpful if stacking multiple lists in the same section.
daysForNewnumberOptionalUsed to highlight new items.

Json Schema​

The input file should comply with the following schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": [
    {
      "type": "object",
      "properties": {
        "link": {
          "type": "object",
          "properties": {
            "text": {
              "type": "string"
            },
            "url": {
              "type": "string"
            },
            "title": {
              "type": "string"
            }
          },
          "required": [
            "text",
            "url",
            "title"
          ]
        },
        "value": {
          "type": "object",
          "properties": {
            "text": {
              "type": "string"
            },
            "title": {
              "type": "string"
            }
          },
          "required": [
            "text",
            "title"
          ]
        },
        "date": {
          "type": "string"
        }
      },
      "required": [
        "link",
        "value",
        "date"
      ]
    }
  ]
}

Example: This json data was generated by a data worflow that gets the new releases of a few projects from GitHub. The system used to build the data workflow is n8n.

[
    {
        "link": {
            "text": "jellyfin/jellyfin",
            "url": "https://github.com/jellyfin/jellyfin/releases/tag/v10.10.7",
            "title": ""
        },
        "value": {
            "text": "v10.10.7",
            "title": "2025-04-05"
        },
        "date": "2025-04-05T19:14:59Z"
    },
    {
        "link": {
            "text": "jellyfin/jellyfin-web",
            "url": "https://github.com/jellyfin/jellyfin-web/releases/tag/v10.10.7",
            "title": ""
        },
        "value": {
            "text": "v10.10.7",
            "title": "2025-04-05"
        },
        "date": "2025-04-05T19:15:00Z"
    },
    {
        "link": {
            "text": "lissy93/dashy",
            "url": "https://github.com/Lissy93/dashy/releases/tag/3.1.1",
            "title": ""
        },
        "value": {
            "text": "3.1.1",
            "title": "2024-05-30"
        },
        "date": "2024-05-30T17:20:53Z"
    },
    {
        "link": {
            "text": "VSCodium/vscodium",
            "url": "https://github.com/VSCodium/vscodium/releases/tag/1.102.14746",
            "title": ""
        },
        "value": {
            "text": "1.102.14746",
            "title": "2025-07-16"
        },
        "date": "2025-07-16T18:27:49Z"
    }
]

Notes​

  • This widget is designed to render data generated by another system that complies with the schema. The example JSON data above was generated using a n8n workflow, and other ETL or workflow systems can generate similar results.
  • To avoid requests to a different system in each refresh, you can save the input files locally in the user-data folder inside your Dashy installation.
  • To use json files from a different domain, remember to add useProxy: true to the widget configuration. I have not tested this use case because I save all my input data locally on the Dashy server. Please open a ticket if you have an issue in this use case.

Example​

This widget renders a json file that from a json-data directory inside the user-data directory on the Dashy server.

  - type: custom-list
    options:
      url: /json-data/github-releases.json
      title: 'Github Releases'
      daysForNew: 5

Info​

  • CORS: 🟢 Not needed for files hosted inside the user-data directory. Use useProxy: true to bypass CORS restrictions when using data from a different server.
  • Auth: 🟢 Not Required
  • Price: 🟢 Free
  • Host: user defined
  • Privacy: depends on the user defined host.

Allows web search using multiple user-defined search engines and other websites.

Options​

FieldTypeRequiredDescription
enginesarrayrequiredAn array of search engine objects. Each search engine object should have two required properties: title and url. See the example below.
placeholderstringoptionalPlaceholder text in the search box.
openingMethodstringoptionalOpen search in one of newtab, sametab or workspace.

Notes​

  • The first search engine in the engines array will be treated as the default search engine, and used when the user presses Enter in the search box.
  • Popup blockers can interfere with opening a new search window.

Example​

This widget allows searching multiple search engines from dashy.

  - type: 'custom-search'
    options:
      placeholder: Search for something using the buttons below
      engines:
      - title: SearXNG
        url: https://searx.lan/?q=
      - title: Quant
        url: https://www.qwant.com/?q=
      - title: Bing Web
        url: http://www.bing.com/search?q=
      - title: Bing Images
        url: http://www.bing.com/images/search?q=
      - title: Bing Maps
        url: http://www.bing.com/maps/search?q=
      - title: Yandex
        url: https://www.yandex.com/search/?text=
      - title: Passmark
        url: https://www.passmark.com/search/zoomsearch.php?zoom_query=
      - title: IMDB
        url: http://www.imdb.com/find?q=

Info​

  • CORS: 🟢 Not needed
  • Auth: 🟢 Not Required
  • Price: 🟢 Free
  • Host: user defined
  • Privacy: depends on the user defined search engines.

RescueTime Overview​

Show an overview of how you have spent your time for the current day.

Options​

FieldTypeRequiredDescription
apiKeystringrequiredThe API-Key generated in the RescueTime UI.

Example​

  - type: rescue-time
    useProxy: true
    options:
      apiKey: abcdefghijkl_mnop

Info​

Minecraft Server​

Show minecraft server status

Options​

FieldTypeRequiredDescription
titlestringOptionalDisplay title for server uses server address if not set.
serverstringRequiredServer hostname or ip(:port) will use srv records.
bedrockbooleanOptionalIf server is a bedrock edition server. (default false)
showModsbooleanOptionalDisplay mod list if available
showPlayersbooleanOptionalDisplay player list if available
showPluginsbooleanOptionalDisplay plugin list if available

Example​

  - type: minecraft-status
    options:
      title: Venity Network
      server: play.venitymc.com
      bedrock: true
      showMods: true
      showPlayers: true
      showPlugins: true

Info​

Self-Hosted Services Widgets​

System Info​

See MVG Datenschutz 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

Note that this widget is not available if you are running Dashy in a container or VM. Instead you can use the System Monitoring widgets to display stats from the host system instead.

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
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

Example​

- type: pi-hole-stats
  options:
    hostname: http://192.168.130.1
    apiKey: xxxxxxxxxxxxxxxxxxxxxxx
tip

To avoid storing secrets in plaintext, both hostname and apiKey can be supplied via environment variables. See Handling Secrets.

Info​

Pi-Hole Stats v6​

Displays the number of queries blocked by Pi-Hole. Use this version of the widget if you have a v6+ Pi-Hole instance.

Options​

FieldTypeRequiredDescription
hostnamestringRequiredThe URL to your Pi-Hole instance
hideStatus / hideChart / hideInfobooleanOptionalOptionally hide any of the three parts of the widget
apiKeystringRequiredYour Pi-Hole web password or application password. It IS your Pi-Hole admin interface password UNLESS you have 2FA turned on (in contrast to the old widget). If you have 2FA turned on you will need to create an application password. Refer to Pi-Hole documentation for how to create an application password.

Example​

- type: pi-hole-stats-v6
  options:
    hostname: http://192.168.130.1
    apiKey: xxxxxxxxxxxxxxxxxxxxxxx
tip

To avoid storing secrets in plaintext, both hostname and apiKey can be supplied via environment variables. See Handling Secrets.

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​

Pi-Hole Queries v6​

Shows top queries that were blocked and allowed by Pi-Hole. Use this version of the widget if you have a v6+ Pi-Hole instance.

Options​

FieldTypeRequiredDescription
hostnamestringRequiredThe URL to your Pi-Hole instance
apiKeystringRequiredYour Pi-Hole web password or application password. It IS your Pi-Hole admin interface password UNLESS you have 2FA turned on (in contrast to the old widget). If you have 2FA turned on you will need to create an application password. Refer to Pi-Hole documentation for how to create an application password.
countnumberOptionalThe number of queries to display. Defaults to 10

Example​

- type: pi-hole-top-queries-v6
  options:
    hostname: https://pi-hole.local
    apiKey: xxxxxxxxxxxxxxxxxxxxxxx

Info​

Pi-Hole Recent Traffic​

Shows number of recent traffic, using allowed and blocked queries from 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

Example​

- type: pi-hole-traffic
  options:
    hostname: https://pi-hole.local
    apiKey: xxxxxxxxxxxxxxxxxxxxxxx

Info​

Pi-Hole Recent Traffic v6​

Shows number of recent traffic, using allowed and blocked queries from Pi-Hole. Use this version of the widget if you have a v6+ Pi-Hole instance.

Options​

FieldTypeRequiredDescription
hostnamestringRequiredThe URL to your Pi-Hole instance
apiKeystringRequiredYour Pi-Hole web password or application password. It IS your Pi-Hole admin interface password UNLESS you have 2FA turned on (in contrast to the old widget). If you have 2FA turned on you will need to create an application password. Refer to Pi-Hole documentation for how to create an application password.

Example​

- type: pi-hole-traffic-v6
  options:
    hostname: https://pi-hole.local
    apiKey: xxxxxxxxxxxxxxxxxxxxxxx

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
groupIdnumberOptionalIf provided, only Services in the given group are displayed. Defaults to 0 in which case all services are displayed.
showChartbooleanOptionalIf provided and false then charts are not displayed. Defaults to true.
showInfobooleanOptionalIf provided and false then information summaries are not displayed. Defaults to true.

Example​

- type: stat-ping
  options:
    hostname: http://192.168.130.1:8080

or

- type: stat-ping
  options:
    hostname: http://192.168.130.1:8080
    groupId: 3
    showChart: false
    showInfo: false

You can use multiple StatPing widgets with different groupIds.

Note, the Group Id is not directly visible in StatPing UI, you can inspect the group select HTML element or the API response to find out.

Info​

Synology Download Station​

Displays the current downloads/torrents tasks of your Synology NAS

Options​

FieldTypeRequiredDescription
hostnamestringRequiredThe URL to your Synology NAS, without a trailing slash
usernamestringRequiredThe username of a user on your synology NAS. You will see only this user download station tasks if he is not part of the administrator group. Currently don't support OTP protected accounts.
passwordstringRequiredThe password of the account specified above.

Example​

- type: synology-download
  options:
    hostname: http://192.168.1.1:8080
    username: dashy
    password: totally-secure-password

Info​

AdGuard Home Block Stats​

Fetches data from your AdGuard Home instance, and displays total number of allowed and blocked queries, plus a pie chart showing breakdown by block type.

Options​

FieldTypeRequiredDescription
hostnamestringRequiredThe URL to your AdGuard Home instance
usernamestringOptionalIf you've got auth enabled on AdGuard, provide your username here
passwordstringOptionalIf you've got auth enabled on AdGuard, provide your password here

Example​

- type: adguard-stats
  useProxy: true
  options:
    hostname: http://127.0.0.1
    username: admin
    password: test

Info​

AdGuard Home Filters​

Fetches data from your AdGuard Home instance, to display the current status of each of your filter lists. Includes filter name, last updated, number of items, and a link to the list.

Options​

FieldTypeRequiredDescription
hostnamestringRequiredThe URL to your AdGuard Home instance
usernamestringOptionalIf you've got auth enabled on AdGuard, provide your username here
passwordstringOptionalIf you've got auth enabled on AdGuard, provide your password here
showOnOffStatusOnlybooleanOptionalIf set to true, will only show aggregated AdGuard filter status (on/off), instead of a list of filters

Example​

- type: adguard-filter-status
  useProxy: true
  options:
    hostname: http://127.0.0.1
    username: admin
    password: test
    showOnOffStatusOnly: false

Info​

AdGuard Home DNS Info​

Fetches data from your AdGuard Home instance, and displays the current status (Enabled / Disabled) of AdGuard DNS. Click show more to view detailed info, including upstream DNS provider, active ports, and the status of DNSSEC, EDNS CS, PTR and IPv6.

Options​

FieldTypeRequiredDescription
hostnamestringRequiredThe URL to your AdGuard Home instance
usernamestringOptionalIf you've got auth enabled on AdGuard, provide your username here
passwordstringOptionalIf you've got auth enabled on AdGuard, provide your password here
showFullInfobooleanOptionalIf set to true, the full DNS info will be shown by default, without having to click "Show Info"

Example​

- type: adguard-dns-info
  useProxy: true
  options:
    hostname: http://127.0.0.1
    username: admin
    password: test
    showFullInfo: false

Info​

AdGuard Home Top Domains​

Fetches data from your AdGuard Home instance, and displays a list of the most queried, and most blocked domains.

Options​

FieldTypeRequiredDescription
hostnamestringRequiredThe URL to your AdGuard Home instance
usernamestringOptionalIf you've got auth enabled on AdGuard, provide your username here
passwordstringOptionalIf you've got auth enabled on AdGuard, provide your password here
limitnumberOptionalSpecify the number of results to show, between 1 and 100, defaults to 10
hideBlockedDomainsbooleanOptionalDon't show the blocked domains list (queried domains only)
hideQueriedDomainsbooleanOptionalDon't show the queried domains list (blocked domains only)

Example​

- type: adguard-top-domains
  useProxy: true
  options:
    hostname: http://127.0.0.1
    username: admin
    password: test
    limit: 10

Info​

Nextcloud User​

Nextcloud is a self hosted productivity platform, it can also be used free of charge with hundreds of existing hosting providers that offer a free Nextcloud account.

Displays branding information of a Nextcloud server (logo, url, slogan) and some user details (name, login name, last login, disk space or quota). Use with regular or admin user.

Shows quota usage when quota is enabled for the user or disk usage when not enabled.

Known issues: the User API incorrectly reports available disk space as total for admin users when quota is not enabled (which usually is the case for admins).

nextcloud-user

Options​

FieldTypeRequiredDescription
hostnamestringRequiredThe URL of the Nextcloud server
usernamestringRequiredNextcloud username
passwordstringRequiredNextcloud app-password (create one in Settings -> Security)

Example​

- type: nextcloud-user
  useProxy: true
  options:
    hostname: https://nextcloud.example.com
    username: alice
    password: xxxxx-xxxxx-xxxxx-xxxxx

Info​

Nextcloud User Statuses​

Show user statuses for selected users.

nextcloud-userstatus

Options​

FieldTypeRequiredDescription
hostnamestringRequiredThe URL of the Nextcloud server
usernamestringRequiredNextcloud username
passwordstringRequiredNextcloud app-password (create one in Settings -> Security)
usersarrayRequiredNextcloud User IDs to show statuses for, list size between 1 and 100
showEmptybooleanOptionalShow statuses without a message, defaults to true

Example​

- type: nextcloud-user-status
  useProxy: true
  options:
    hostname: https://nextcloud.example.com
    username: alice
    password: xxxxx-xxxxx-xxxxx-xxxxx
    users: ['bob', 'alice']

Info​

Nextcloud Notifications​

Displays your notifications and allows deleting them.

nextcloud-notifications

Options​

FieldTypeRequiredDescription
hostnamestringRequiredThe URL of the Nextcloud server
usernamestringRequiredNextcloud username
passwordstringRequiredNextcloud app-password (create one in Settings -> Security)
limitnumber|stringOptionalLimit displayed notifications either by count, e.g. 5 to show the 5 most recent, or by age, e.g. 1d to only show notifications not older than a day. Accepted suffixes for age limit are m, h and d.

Example​

- type: nextcloud-notifications
  useProxy: true
  options:
    hostname: https://nextcloud.example.com
    username: alice
    password: xxxxx-xxxxx-xxxxx-xxxxx
    limit: 6h

Info​

Nextcloud System​

Visualises overall memory utilisation and CPU load averages, shows server versions.

nextcloud-system

Options​

FieldTypeRequiredDescription
hostnamestringRequiredThe URL of the Nextcloud server
usernamestringRequiredMust be a Nextcloud admin user
passwordstringRequiredNextcloud app-password (create one in Settings -> Security)

Example​

- type: nextcloud-system
  useProxy: true
  options:
    hostname: https://nextcloud.example.com
    username: alice
    password: xxxxx-xxxxx-xxxxx-xxxxx

Info​

Nextcloud Stats​

Shows key usage statistics about your Nextcloud server.

nextcloud-stats

Options​

FieldTypeRequiredDescription
hostnamestringRequiredThe URL of the Nextcloud server
usernamestringRequiredMust be a Nextcloud admin user
passwordstringRequiredNextcloud app-password (create one in Settings -> Security)

Example​

- type: nextcloud-stats
  useProxy: true
  options:
    hostname: https://nextcloud.example.com
    username: alice
    password: xxxxx-xxxxx-xxxxx-xxxxx

Info​

Nextcloud PHP OPcache Stats​

Shows statistics about PHP OPcache performance on your Nextcloud server.

nextcloud-phpopcache

Options​

FieldTypeRequiredDescription
hostnamestringRequiredThe URL of the Nextcloud server
usernamestringRequiredMust be a Nextcloud admin user
passwordstringRequiredNextcloud app-password (create one in Settings -> Security)

Example​

- type: nextcloud-php-opcache
  useProxy: true
  options:
    hostname: https://nextcloud.example.com
    username: alice
    password: xxxxx-xxxxx-xxxxx-xxxxx

Info​

ntfy stream​

Subscribes to topics on a private ntfy server, and shows new messages as they arrive.

Options​

FieldTypeRequiredDescription
server_urlstringRequiredThe server url
topicstringRequiredA topic, or a comma separated list of topics
authstringoptionalAn auth string. ⚠️ This is sent as query parameter.
titlestringoptionalA title for the widget.

Example​

- type: ntfy-stream
  useProxy: false
  options:
    title: NTFY stream
    server_url: https://myntfy.server.tld
    topic: alert,warning,mytopic

Info​

Proxmox lists​

Shows lists of nodes, containers, and VMs in a Proxmox virtual environment cluster, with a status indicator.

Options​

FieldTypeRequiredDescription
cluster_urlstringRequiredThe URL of the proxmox cluster server. No trailing /. for example: https://proxmox.lan:8006
user_namestringRequiredA Proxmox API Username, for example root@pam or dashy@pve.
token_namestringRequiredA Proxmox API token name. You can get a token in the API section of the cluster management interface.
token_uuidstringRequiredThe value of the token entered above. This is normally a UUID.
nodestringoptionalA Proxmox node name. If empty or not supplied, a list of nodes will be shown.
node_datastringoptionalThis is required if a node is selected, Currently this accepts two values, either lxc or qemu but the widget can be improved to get other types of data from the Proxmox API.
titlestringoptionalA widget title.
title_as_linkbooleanoptionalWhen this is set to anything other than 0 or false, the title will be linked to the value entered in the cluster_url option.
footerstringoptionalA widget footer.
footer_as_linkbooleanoptionalWhen this is set to anything other than 0 or false, the title will be linked to the value entered in the cluster_url option.
hide_templatesbooleanoptionalWhen this is set to anything other than 0 or false, templates will be filtered out of the result list.

Example​

This will show the list of nodes.

  - type: proxmox-lists
    useProxy: true 
    options:
      cluster_url: https://proxmox.lan:8006
      user_name: root@pam
      token_name: dashy
      token_uuid: bfb152df-abcd-abcd-abcd-ccb95a472d01

This will show the list of VMs, with a title and a linked fotter, hiding VM templates.

  - type: proxmox-lists
    useProxy: true 
    options:
      cluster_url: https://proxmox.lan:8006
      user_name: root@pam
      token_name: dashy
      token_uuid: bfb152df-abcd-abcd-abcd-ccb95a472d01
      node: proxmox
      node_data: qemu
      title: Proxmox VMs
      title_as_link: false
      footer: Proxmox
      footer_as_link: true
      hide_templates: 1

Info​

Troubleshooting​

  • 404 Error in development mode: The error might disappear in production mode yarn start
  • 500 Error in production mode: Try adding the certificate authority (CA) certificate of your Proxmox host to Node.js.
    • Download the Proxmox CA certificate to your Dashy host.
    • Export environment variable NODE_EXTRA_CA_CERTS and set its value to the path of the downloaded CA certificate. Example: export NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/devlab_ca.pem

Sabnzbd​

Shows queue information regarding your self hosted Sabnzbd server.

Sabnzbd

Options​

FieldTypeRequiredDescription
sabnzbdUrlstringRequiredThe URL of the Sabnzbd server. No trailing /.
apiKeystringRequiredAPI key for Sabnzbd access. Located under Config -> General -> Security -> API Key.
hideDetailsbooleanOptionalHides extra server queue details.
hideQueuebooleanOptionalHides the queue list in an expandable dropdown.

Example​

  - type: sabnzbd
    options:
      sabnzbdUrl: 'https://sabnzbd.example.com'
      apiKey: XXXXXXXXXXXXXXXXXX
      hideDetails: false
      hideQueue: false

Info​

Gluetun VPN Info​

Display info from the Gluetun VPN container public IP API. This can show the IP and location data for the exit VPN node.

Options​

FieldTypeRequiredDescription
visibleFieldsstringRequiredA comma separated list of the fields you want visible in the widget. You can have any number of the following : public_ip, region, country, city, location, organisation, postal_code, timezone. Defaults to just public_ip
hoststringRequiredThe url to the gluetun HTTP control server. E.g. http://gluetun:8000

Example​

- type: gluetun-status
  useProxy: true
  options:
    hostname: http://server-or-conatiner-hostname:8000
    visibleFields: public_ip,region,country,city,location,organisation,postal_code,timezone

Info​

  • CORS: 🟠 Proxied
  • Auth: 🟢 Required
  • Price: 🟢 Free
  • Host: Self-Hosted (see Gluetun)
  • Privacy: See Gluetun Wiki

Drone CI Builds​

Display the last builds from a Drone CI instance. A self-hosted CI system that uses docker.

Options​

FieldTypeRequiredDescription
hoststringRequiredThe hostname of the Drone CI instance.
apiKeystringRequiredThe API key (https://[your-drone-instance]/account).
limitintegerOptionalLimit the amounts of listed builds.
repostringOptionalShow only builds of the specified repo

Example​

- type: drone-ci
  updateInterval: 30
  options:
    host: https://drone.somedomain.com
    apiKey: my-very-secret-api-key
    limit: 10

Info​

  • CORS: 🟢 Enabled
  • Auth: 🟢 Required
  • Price: 🟢 Free
  • Host: Self-Hosted (see Drone)
  • Privacy: See Drone

Filebrowser​

Displays storage statistics and file listings from a Filebrowser Quantum instance. Shows directory size, file/folder counts, favorite files, and recently modified files with quick-access links.

Options​

FieldTypeRequiredDescription
hostnamestringRequiredThe URL of your Filebrowser instance
apiKeystringRequiredA long-lived API key (create in Settings → API Keys)
sourcestringOptionalThe source/scope name to browse. Defaults to the first available source
pathstringOptionalThe directory path to display. Defaults to /
favoritesarrayOptionalList of filenames to show as quick-access favorites
showRecentnumberOptionalNumber of recently modified files to display. Defaults to 5, set to 0 to disable
limitnumberOptionalMaximum number of files to display per section. Defaults to 10
hideStatsbooleanOptionalIf true, hides the storage statistics section
hideFavoritesbooleanOptionalIf true, hides the favorites section
hideRecentbooleanOptionalIf true, hides the recent files section
showDetailedStatsbooleanOptionalIf true, shows additional statistics including last modified date, largest file, hidden file count, total items, and file type breakdown. Defaults to false

Example​

Basic usage:

- type: filebrowser
  useProxy: true
  options:
    hostname: http://filebrowser.local:8080
    apiKey: DASHY_FILEBROWSER_KEY
    source: Documents
    path: /
    showRecent: 5
    favorites:
      - important-notes.txt
      - config.yaml

With detailed statistics:

- type: filebrowser
  useProxy: true
  options:
    hostname: http://filebrowser.local:8080
    apiKey: DASHY_FILEBROWSER_KEY
    source: Downloads
    showDetailedStats: true
    showRecent: 10
    limit: 15

Widget Sections​

The widget displays up to four sections:

  1. Storage Stats - Directory name, total size, file and folder counts
  2. Detailed Stats (optional) - Last modified date, largest file, hidden file count, total items, and file type breakdown with badges
  3. Favorites - Quick-access links to user-specified files
  4. Recent Files - Most recently modified files sorted by date

Info​

  • CORS: 🟠 Proxied
  • Auth: 🟢 Required
  • Price: 🟢 Free
  • Host: Self-Hosted (see Filebrowser Quantum)
  • Privacy: Self-Hosted

Linkding​

Linkding is a self-hosted bookmarking service, which has a clean interface and is simple to set up. This lists the links, filterable by tags.

Options​

FieldTypeRequiredDescription
hoststringRequiredThe hostname of the Drone CI instance.
apiKeystringRequiredThe API key (https://your-linkding-instance/settings/integrations).
tagslist of stringOptionalFilter the links by tag.

Example​

- type: linkding
  updateInterval: 30
  options:
    host: https://lingding.somedomain.com
    apiKey: my-very-secret-api-key
    tags: 
      - rpg
      - markdown

Info​

  • CORS: 🟢 Enabled
  • Auth: 🟢 Required
  • Price: 🟢 Free
  • Host: Self-Hosted (see Linkding)
  • Privacy: See Linkding

Uptime Kuma​

Uptime Kuma is an easy-to-use self-hosted monitoring tool.

Options​

FieldTypeRequiredDescription
urlstringRequiredThe URL of the Uptime Kuma instance
apiKeystringRequiredThe API key (see https://github.com/louislam/uptime-kuma/wiki/API-Keys).

Example​

- type: uptime-kuma
  useProxy: true
  options:
    apiKey: uk2_99H0Yd3I2pPNIRfn0TqBFu4g5q85R1Mh75yZzw6H
    url: http://192.168.1.106:3691/metrics

Info​

  • CORS: 🟢 Enabled
  • Auth: 🟢 Required
  • Price: 🟢 Free
  • Host: Self-Hosted (see Uptime Kuma )
  • Privacy: See Uptime Kuma

Uptime Kuma Status Page​

Uptime Kuma is an easy-to-use self-hosted monitoring tool.

Options​

FieldTypeRequiredDescription
hoststringRequiredThe URL of the Uptime Kuma instance
slugstringRequiredThe slug of the status page
monitorNamesstrinsOptionalNames of monitored services (in the same order as on the kuma uptime status page)

Example​

- type: uptime-kuma-status-page
  options:
    host: http://localhost:3001
    slug: another-beautiful-status-page
    monitorNames:
      - "Name1"
      - "Name2"

Info​

  • CORS: 🟢 Enabled
  • Auth: 🟢 Not Needed
  • Price: 🟢 Free
  • Host: Self-Hosted (see Uptime Kuma )
  • Privacy: See Uptime Kuma

Tactical RMM​

Tactical RMM is a self-hosted remote monitoring & management tool.

Capture

Options​

FieldTypeRequiredDescription
urlstringRequiredThe status endpoint URL (https://api.example.com/core/v2/status/)
tokenstringRequiredThe MON_TOKEN (see https://docs.tacticalrmm.com/tipsntricks/#monitor-your-trmm-instance-via-the-built-in-monitoring-endpoint).

Example​

- type: trmm
  useProxy: true
  options:
    token: PkPVKMzbmXgeQDlJWb0WXYvsIk3JvZyadURud2cSTdMia6hUbQ
    url: https://api.example.com/core/v2/status/

Info​

  • CORS: 🟠 Proxied
  • Auth: 🟢 Required
  • Price: 🟢 Free
  • Host: Self-Hosted (see Tactical RMM )
  • Privacy: See Tactical RMM

System Resource Monitoring​

Glances​

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.

If you are using Docker to run glances make sure to add the enviroment variable -e TZ = {YourTimeZone}. You can get a list of valid timezones by running timedatectl list-timezones on any linux system. This is needed so the graphs show the currect time.

Here an example for Docker

 docker run -d \
    --name glances \
    --restart unless-stopped \
    -v /var/run/docker.sock:/var/run/docker.sock:ro \
    -p 61208:61208 \
    --pid host \
    --privileged \
    -e GLANCES_OPT=-w \
    -e PUID=1000 \
    -e PGID=1000 \
    -e TZ=Europe/Zurich \
    nicolargo/glances:latest

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.

If Glances is running on a Windows system it is recommended to add the following arguments --disable-plugin all --enable-plugin cpu,mem,diskio,ip,network,containers,quicklook,load,fs,alert -w This is due to Glances not being that stable on windows, so disabling all plugins that aren't used by Dashy widgets can save on ressources.

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

Note that if auth is configured, requests must be proxied with useProxy: true

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 all cores

Example​

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

Current CPU Usage Speedometer​

Speedometer styled version of the Current CPU Usage widget

Example​

- type: gl-cpu-speedometer
  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

Current Memory Usage Speedometer​

Speedometer styled version of the Current Memory Usage widget

Example​

- type: gl-mem-speedometer
  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

Uptime​

Displays the system uptime fetched from Glances.

Example​

- type: gl-uptime
  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

IP Address​

Shows public and private IP address. Note that the ip plugin is not available on all instances of Glances.

Example​

- type: gl-ip-address
  options:
    hostname: http://192.168.130.2:61208

CPU Temp​

Displays temperature data from system CPUs.

Note: This widget uses the sensors plugin, which is disabled by default, and may cause performance issues. You'll need to enable the sensors plugin to use this widget, using: --enable-plugin sensors when you start Glances.

Options​

FieldTypeRequiredDescription
unitsstringOptionalUse C to display temperatures in Celsius or F to use Fahrenheit. Defaults to C.

Example​

- type: gl-cpu-temp
  options:
    hostname: http://192.168.130.2:61208
    units: C

GPU​

Displays usage, memory and temperature for each NVIDIA GPU, plus fan speed where available.

Note: This widget uses the gpu plugin, which requires the py3nvml library and is limited to NVIDIA chipsets.

Options​

FieldTypeRequiredDescription
unitsstringOptionalUse C to display temperatures in Celsius or F to use Fahrenheit. Defaults to C.

Example​

- type: gl-gpu
  options:
    hostname: http://192.168.130.2:61208
    units: C

Compact Metrics​

A multi-system overview widget that displays CPU, memory and disk usage for multiple Glances instances in a compact table. Click on a row to see detailed metrics for that system.

Options​

FieldTypeRequiredDescription
systemsarrayRequiredAn array of systems to monitor, each with header (display name) and url (Glances base URL)
apiVersionnumberOptionalGlances API version. Defaults to 4
usernamestringOptionalIf Glances is password-protected, specify the username
passwordstringOptionalIf Glances is password-protected, specify the password

Example​

- type: gl-compact-metrics
  options:
    systems:
      - header: Server 1
        url: http://192.168.1.10:61208
      - header: Server 2
        url: http://192.168.1.11:61208
      - header: NAS
        url: http://192.168.1.20: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'

You can also use this widget to display an image, wither locally or from a remote origin.

- type: embed
  options:
    html: '<img src="https://dashy.lan/item-icons/my-image.png" />'

API Response​

Display data from any HTTP/JSON API endpoint. Fetch a URL, then declaratively map response fields to labelled, formatted values. This was very much inspired by, and is broadly compatible with Homepage's customapi widget

Options​

FieldTypeRequiredDescription
urlstringRequiredThe full URL of the API endpoint to fetch
refreshIntervalnumberOptionalHow often to refetch, in milliseconds. Defaults to 10000 (10s). If omitted, the widget-level updateInterval (in seconds) is used instead
usernamestringOptionalUsername for HTTP basic auth
passwordstringOptionalPassword for HTTP basic auth
methodstringOptionalHTTP method, e.g. GET (default) or POST
headersobjectOptionalAn object of custom request headers
requestBodystring or objectOptionalRequest body for non-GET methods. Prefer an object. A raw string is JSON-encoded again, so don't pre-stringify
displaystringOptionalLayout for the fields: block (default, label and value on one row) or list (value stacked under the label)
mappingsarrayOptionalThe fields to display from the response (see below). If omitted, the raw response root is shown

Each item in mappings accepts:

FieldTypeRequiredDescription
fieldstringOptionalDot-path to the value, e.g. path.to.key or items.0.name. Omit to use the response root (useful with size)
labelstringOptionalLabel shown beside the value
formatstringOptionalOne of text (default), number, percent, bytes, bitrate, duration, date, relativeDate or size
scalenumber or stringOptionalMultiply the value before formatting. A number or fraction string, e.g. 1024 or 1/16
prefixstringOptionalText prepended to the formatted value
suffixstringOptionalText appended to the formatted value
remaparrayOptionalSwap raw values for display text, e.g. 0 → Down. Each entry has value and to; an entry with any: true matches everything else
localestringOptionalLocale for number/percent/date/relativeDate, e.g. nl. Defaults to the browser locale
dateStylestringOptionalFor date format. One of full, long (default), medium, short
timeStylestringOptionalFor date format. One of full, long, medium, short
stylestringOptionalFor relativeDate format. One of long (default), short, narrow
numericstringOptionalFor relativeDate format. One of always (default) or auto
additionalFieldobjectOptionalA secondary value shown next to the main one. Accepts field, format (and its options), plus color - one of theme, adaptive (action colour from the value's sign: positive green, negative red), black or white

Notes:

  • percent treats the value as an already-computed percentage, so 42 is shown as 42%
  • bytes and bitrate auto-select a unit: 1073741824 → 1 GB, 2500000 → 2.5 Mbps
  • duration shows seconds as a compact time: 3665 → 1h 1m
  • scale is applied before formatting, useful for unit conversions — e.g. for an API reporting kilobytes, scale: 1024 with format: bytes
  • size returns the number of items in an array (or keys in an object) — pair it with an omitted field to count the response root
  • For APIs that don't send CORS headers (most self-hosted services), set the widget-level useProxy: true to route the request through Dashy's server-side proxy

Example​

- type: customapi
  options:
    url: https://api.github.com/repos/lissy93/dashy
    refreshInterval: 60000
    mappings:
      - field: stargazers_count
        label: Stars
        format: number
      - field: open_issues_count
        label: Open Issues
        format: number
      - field: pushed_at
        label: Last Push
        format: relativeDate

Or, human-readable disk usage from a Glances instance:

- type: customapi
  useProxy: true
  options:
    url: http://192.168.0.1:61208/api/4/fs
    mappings:
      - field: 0.mnt_point
        label: Mount
      - field: 0.used
        label: Used
        format: bytes
      - field: 0.percent
        label: Used %
        format: percent

Info​

  • CORS: 🟠 Depends on target API (use useProxy: true if blocked)
  • Auth: 🟠 Optional (basic auth or custom headers)
  • Price: 🟢 Free

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/endpoints/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

Alternatively, and more securely, 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

Handling Secrets​

Some widgets require you to pass potentially sensitive info such as API keys. The conf.yml is not ideal for this, as it's stored in plaintext. Instead, for secrets you should use environment variables.

In your widget options, set the value to the name of an environment variable starting with DASHY_ (or VITE_APP_ / VUE_APP_ for backwards compatibility). The Dashy server will substitute it with the matching process.env value when proxying the request.

The widget must be set to route through the Dashy server with useProxy: true. Without this, the placeholder is sent directly to the upstream API and will fail. Substitution covers the request URL, headers and body, so any auth pattern (Bearer, Basic, query param, POST body) works.

For more information about setting and managing your environment variables, see Management Docs --> Environmental Variables.

For example:

- type: weather
  useProxy: true
  options:
    apiKey: DASHY_WEATHER_TOKEN
    city: London
    units: metric
    hideDetails: true

Then set DASHY_WEATHER_TOKEN='xxx' in your container or local environment, and restart Dashy. To rotate the value, just update the env var and restart. No rebuild required.

note

Only env vars starting with DASHY_, VITE_APP_ or VUE_APP_ are eligible for substitution. Other server-side env vars are never exposed.

If you build Dashy from source yourself, VITE_APP_* and DASHY_* vars set at build time are also baked into the bundle by Vite, which works without useProxy: true.

Setting Timeout​

If the endpoint you are requesting data from is slow to respond, you may see a timeout error in the console. This can easily be fixed by specifying the timeout property on the offending widget. This should be an integer value, in milliseconds. By default timeout is 2500 ms (2½ seconds).

For example:

- type: gl-current-cpu
  timeout: 8000
  options:
    hostname: https://glances.dns-device.local

Adding Labels​

If you have multiple widgets of the same type in a single section, it may not be clear what each one is. To overcome this, you can add a custom label to any given widget, using the label property.

For example:

- name: CPU Usage
  icon: fas fa-tachometer
  widgets:
  - type: gl-current-cpu
    label: Meida Server
    options:
      hostname: http://media-server.lan:61208
  - type: gl-current-cpu
    label: Firewall
    options:
      hostname: http://firewall.lan:61208
  - type: gl-current-cpu
    label: File Sync Server
    options:
      hostname: http://file-sync.lan:61208

Ignoring Errors​

When there's an error fetching or displaying a widgets data, then it will be highlighted in yellow, and a message displayed on the UI.

In some instances, this is a false positive, and the widget is actually functioning correctly. If this is the case, you can disable the UI error message of a given widget by setting: ignoreErrors: true

- type: gl-disk-io
  ignoreErrors: true
  options:
    hostname: https://glances.dns-device.local

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.

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

You can suggest a widget here, please star the repo before submitting a ticket. If you are a monthly GitHub sponsor, I will happily build out a custom widget for any service that meets the above criteria, usually within 2 weeks of initial request.

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.

Troubleshooting Widget Errors​

If an error occurs when fetching or rendering results, you will see a short message in the UI. If that message doesn't adequately explain the problem, then you can open the browser console to see more details.

Before proceeding, ensure that if the widget requires auth your API is correct, and for custom widgets, double check that the URL and protocol is correct.

If you're able to, you can find more information about why the request may be failing in the Dev Tools under the Network tab, and you can ensure your endpoint is correct and working using a tool like Postman.

CORS Errors​

The most common issue is a CORS error. This is a browser security mechanism which prevents the client-side app (Dashy) from from accessing resources on a remote origin, without that server's explicit permission (e.g. with headers like Access-Control-Allow-Origin). See the MDN Docs for more info: Cross-Origin Resource Sharing.

There are several ways to fix a CORS error:

Option 1 - Ensure Correct Protocol​

You will get a CORS error if you try and access a http service from a https source. So ensure that the URL you are requesting has the right protocol, and is correctly formatted.

Option 2 - Set Headers​

If you have control over the destination (e.g. for a self-hosted service), then you can simply apply the correct headers. Add the Access-Control-Allow-Origin header, with the value of either * to allow requests from anywhere, or more securely, the host of where Dashy is served from. For example:

Access-Control-Allow-Origin: https://url-of-dashy.local

or

Access-Control-Allow-Origin: *

Option 3 - Proxying Request​

You can route requests through Dashy's built-in CORS proxy. Instructions and more details can be found here. If you don't have control over the target origin, and you are running Dashy either through Docker, with the Node server or on Netlify, then this solution will work for you.

Just add the useProxy: true option to the failing widget.

Option 4 - Use a plugin​

For testing purposes, you can use an addon, which will disable the CORS checks. You can get the Allow-CORS extension for Chrome or Firefox, more details here

Raising an Issue​

If you need to submit a bug report for a failing widget, then please include the full console output (see how) as well as the relevant parts of your config file. Before sending the request, ensure you've read the docs. If you're new to GitHub, an haven't previously contributed to the project, then please fist star the repo to avoid your ticket being closed by the anti-spam bot.