33 KiB
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 options are optional.
Options
Field | Type | Required | Description |
---|---|---|---|
timeZone |
string |
Optional | The 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 |
format |
string |
Optional | A 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 |
hideDate |
boolean |
Optional | If set to true , the date and city will not be shown. Defaults to false |
Example
- type: clock
options:
timeZone: Europe/London
format: en-GB
hideDate: false
Weather
A simple, live-updating local weather component, showing temperature, conditions and more info.
Options
Field | Type | Required | Description |
---|---|---|---|
apiKey |
string |
Required | Your OpenWeatherMap API key. You can get one for free at openweathermap.org |
city |
string |
Required | A city name to use for fetching weather. This can also be a state code or country code, following the ISO-3166 format |
units |
string |
Optional | The units to use for displaying data, can be either metric or imperial . Defaults to metric |
hideDetails |
boolean |
Optional | If set to true , the additional details (wind, humidity, pressure, etc) will not be shown. Defaults to false |
Example
- type: weather
options:
apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
city: London
units: metric
hideDetails: false
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
Field | Type | Required | Description |
---|---|---|---|
apiKey |
string |
Required | Your OpenWeatherMap API key. You can get one for free at openweathermap.org |
city |
string |
Required | A city name to use for fetching weather. This can also be a state code or country code, following the ISO-3166 format |
numDays |
number |
Optional | The number of days to display of forecast info to display. Defaults to 4 , max 16 days |
units |
string |
Optional | The units to use for displaying data, can be either metric or imperial . Defaults to metric |
hideDetails |
boolean |
Optional | If 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
Crypto Watch List
Keep track of price changes of your favorite crypto assets. Data is fetched from CoinGecko
Options
Field | Type | Required | Description |
---|---|---|---|
assets |
string |
Optional | An 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 |
currency |
string |
Optional | The fiat currency to display price in, expressed as an ISO-4217 alpha code (see list of currencies). Defaults to USD |
sortBy |
string |
Optional | The method of sorting results. Can be marketCap , volume or alphabetical . Defaults to marketCap . |
limit |
number |
Optional | Number 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
Crypto Token Price History
Shows recent price history for a given crypto asset, using price data fetched from CoinGecko
Options
Field | Type | Required | Description |
---|---|---|---|
asset |
string |
Required | Name of a crypto asset, coin or token to fetch price data for, see list of supported assets |
currency |
string |
Optional | The fiat currency to display results in, expressed as an ISO-4217 alpha code (see list of currencies). Defaults to USD |
numDays |
number |
Optional | The number of days of price history to render. Defaults to 7 , min: 1 , max: 30 days |
chartColor |
string |
Optional | Color of the chart value. Defaults to --widget-text-color which inherits dashboard primary color |
chartHeight |
number |
Optional | The height of rendered chart in px. Defaults to 300 |
Example
- type: crypto-price-chart
options:
asset: bitcoin
currency: GBP
numDays: 7
RSS Feed
Display news and updates from any RSS-enabled service.
Options
Field | Type | Required | Description |
---|---|---|---|
rssUrl |
string |
Required | The URL location of your RSS feed |
apiKey |
string |
Optional | An API key for rss2json. It's free, and will allow you to make 10,000 requests per day, you can sign up here |
limit |
number |
Optional | The number of posts to return. If you haven't specified an API key, this will be limited to 10 |
orderBy |
string |
Optional | How results should be sorted. Can be either pubDate , author or title . Defaults to pubDate |
orderDirection |
string |
Optional | Order direction of feed items to return. Can be either asc or desc . Defaults to desc |
Example
- type: rss-feed
options:
rssUrl: https://www.schneier.com/blog/atom.xml
apiKey: xxxx
XKCD Comics
Have a laugh with the daily comic from XKCD. A classic webcomic website covering everything from Linux, math, romance, science and language.
Options
Field | Type | Required | Description |
---|---|---|---|
comic |
string / number |
Optional | Choose 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
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
Field | Type | Required | Description |
---|---|---|---|
username |
string |
Required | Your CodeStats username |
hostname |
string |
Optional | If your self-hosting CodeStats, then supply the host name. By default it will use the public hosted instance |
monthsToShow |
number |
Optional | Specify the number of months to render in the historical data chart. Defaults to 6 |
hideMeta |
boolean |
Optional | Optionally hide the meta section (username, level, all-time and recent XP) |
hideHistory |
boolean |
Optional | Optionally hide the historical calendar heat map |
hideLanguages |
boolean |
Optional | Optionally hide the programming languages pie chart |
hideMachines |
boolean |
Optional | Optionally hide the machines percentage chart |
Example
- type: code-stats
options:
username: alicia
Public Holidays
Counting down to the next day off work? This widget displays upcoming public holidays for your country. Data is fetched from Enrico
Options
Field | Type | Required | Description |
---|---|---|---|
country |
string |
Required | The region to fetch holiday data for, specified as a country code, e.g. GB or US |
holidayType |
string |
Optional | The type of holidays to fetch. Can be: all , public_holiday , observance , school_holiday , other_day or extra_working_day . Defaults to public_holiday |
monthsToShow |
number |
Optional | The number of months in advance to show. Min: 1 , max: 24 . Defaults to 12 |
Example
- type: public-holidays
options:
country: GB
holidayType: all
monthsToShow: 12
TFL Status
Shows real-time tube status of the London Underground. All options are optional.
Options
Field | Type | Required | Description |
---|---|---|---|
showAll |
boolean |
Optional | By 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 |
sortAlphabetically |
boolean |
Optional | By default lines are sorted by current status, set this option to true to instead sort them alphabetically |
linesToShow |
array |
Optional | By 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
Exchange Rates
Display current FX rates in your native currency
Options
Field | Type | Required | Description |
---|---|---|---|
apiKey |
string |
Required | API key for exchangerate-api.com, usually a 24-digit alpha-numeric string. You can sign up for a free account here |
inputCurrency |
string |
Required | The 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 |
outputCurrencies |
array |
Required | List 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 |
Example
- type: exchange-rates
options:
apiKey: xxxxxxxxxxxxxxxxxxxxxxxx
inputCurrency: GBP
outputCurrencies:
- USD
- JPY
- HKD
- KPW
Stock Price History
Shows recent price history for a given publicly-traded stock or share
Options
Field | Type | Required | Description |
---|---|---|---|
apiKey |
string |
Required | API key for Alpha Vantage, you can get a free API key here |
stock |
string |
Required | The stock symbol for the asset to fetch data for |
priceTime |
string |
Optional | The time to fetch price for. Can be high , low , open or close . Defaults to high |
chartColor |
string |
Optional | Color of the chart value. Defaults to --widget-text-color which inherits dashboard primary color |
chartHeight |
number |
Optional | The height of rendered chart in px. Defaults to 300 |
Example
- type: stock-price-chart
options:
stock: NET
apiKey: PGUWSWD6CZTXMT8N
Joke
Renders a programming or generic joke. Data is fetched from the JokesAPI by @Sv443
Options
Field | Type | Required | Description |
---|---|---|---|
category |
string |
Optional | Set 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 |
safeMode |
boolean |
Optional | Set to true , to prevent the fetching of any NSFW jokes. Defaults to false |
language |
string |
Optional | Specify 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
News Headlines
Displays the latest news, click to read full article. Date is fetched from various news sources using Currents API
Options
Field | Type | Required | Description |
---|---|---|---|
apiKey |
string |
Required | Your API key for CurrentsAPI. This is free, and you can get one here |
country |
string |
Optional | Fetch 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 |
category |
string |
Optional | Only return news from within a given category, e.g. sports , programming , world , science . The following categories are supported |
lang |
string |
Optional | Specify the language for returned articles as a 2-digit ISO code (limited article support). The following languages are supported, defaults to en |
count |
number |
Optional | Limit the number of results. Can be between 1 and 200 , defaults to 10 |
keywords |
string |
Optional | Only return articles that contain an exact match within their title or description |
Example
- type: news-headlines
options:
apiKey: xxxxxxx
category: world
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
Field | Type | Required | Description |
---|---|---|---|
airport |
string |
Required | The 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 ) |
apiKey |
string |
Required | A valid RapidAPI Key, with AeroDataBox enabled (check in your Subscription Dashboard). This API is free to sign up for and use |
limit |
number |
Optional | For busy airports, you may wish to limit the number of results visible |
direction |
string |
Optional | By 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
Astronomy Picture of the Day
Show the NASA Astronomy Pictore of the Day. Data is fetched from APOD using PawelPleskaczynski/apod_api.
Options
No config options.
Example
- type: apod
GitHub Trending
Displays currently trending projects on GitHub. Optionally specify a language and time-frame. Data is fetched from Lissy93/gh-trending-no-cors using the GitHub API.
Options
Field | Type | Required | Description |
---|---|---|---|
lang |
string |
Optional | A programming language to fetch trending repos from that category. E.g. javascript or go |
since |
string |
Optional | The timeframe to use when calculating trends. Can be either daily , weekly or monthly . Defaults to daily |
limit |
number |
Optional | Optionally limit the number of results. Max 25 , default is 10 |
Example
- type: github-trending-repos
options:
limit: 8
since: weekly
GitHub Profile Stats
Display stats from your GitHub profile, using embedded cards from anuraghazra/github-readme-stats
Options
Field | Type | Required | Description |
---|---|---|---|
username |
string |
Required | The GitHub username to fetch info for. E.g. lissy93 . (Not required if hideProfileCard and hideLanguagesCard are both set to true ) |
hideProfileCard |
boolean |
Optional | If set to true , the users profile card will not be shown. Defaults to false |
hideLanguagesCard |
boolean |
Optional | If set to true , the users top languages card will not be shown. Defaults to false |
repos |
array |
Optional | If you'd like to also display stats for some GitHub reposotories, then add an array or repo names here. Specified as [username]/[repo-name] , e.g. lissy93/dashy |
Example
- type: github-profile-stats
options:
username: Lissy93
hideLanguagesCard: true
repos:
- lissy93/dashy
- lissy93/personal-security-checklist
- lissy93/twitter-sentiment-visualisation
Public IP
Often find yourself searching "What's my IP", just so you can check your VPN is still connected? This widget displays your public IP address, along with ISP name and approx location. Data is fetched from IP-API.com.
Options
No config options.
Example
- type: public-ip
Self-Hosted Services Widgets
System Info
Displays info about the server which Dashy is hosted on. Includes user + host, operating system, uptime and basic memory & load data.
Options
No config options.
Example
- type: system-info
Cron Monitoring (Health Checks)
Cron job monitoring using Health Checks. Both managed and self-hosted instances are supported.
Options
Field | Type | Required | Description |
---|---|---|---|
apiKey |
string |
Required | A read-only API key for the project to monitor. You can generate this by selecting a Project --> Settings --> API Access. Note that you must generate a separate key for each project |
host |
string |
Optional | If you're self-hosting, or using any instance other than the official (healthchecks.io), you will need to specify the host address. E.g. https://healthchecks.example.com or http://cron-monitoing.local |
Example
- type: health-checks
options:
apiKey: XXXXXXXXX
CPU History (NetData)
Pull recent CPU usage history from NetData.
Options
Field | Type | Required | Description |
---|---|---|---|
host |
string |
Required | The URL to your NetData instance |
chartHeight |
number |
Optional | The height of rendered chart in px. Defaults to 300 |
chartColor / chartColors |
string / array |
Optional | Color 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
Memory History (NetData)
Pull recent system RAM usage from NetData, and show as a breakdown of different categories.
Options
Field | Type | Required | Description |
---|---|---|---|
host |
string |
Required | The URL to your NetData instance |
chartHeight |
number |
Optional | The height of rendered chart in px. Defaults to 300 |
chartColor / chartColors |
string / array |
Optional | Color 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
Load History (NetData)
Pull recent load usage in 1, 5 and 15 minute intervals, from NetData.
Options
Field | Type | Required | Description |
---|---|---|---|
host |
string |
Required | The URL to your NetData instance |
chartHeight |
number |
Optional | The height of rendered chart in px. Defaults to 300 |
chartColor / chartColors |
string / array |
Optional | Color 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
Pi Hole Stats
Displays the number of queries blocked by Pi-Hole.
Options
Field | Type | Required | Description |
---|---|---|---|
hostname |
string |
Required | The URL to your Pi-Hole instance |
hideStatus / hideChart / hideInfo |
boolean |
Optional | Optionally hide any of the three parts of the widget |
Example
- type: pi-hole-stats
options:
hostname: http://192.168.130.1
Pi Hole Queries
Shows top queries that were blocked and allowed by Pi-Hole.
Options
Field | Type | Required | Description |
---|---|---|---|
hostname |
string |
Required | The URL to your Pi-Hole instance |
apiKey |
string |
Required | Your 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 |
count |
number |
Optional | The number of queries to display. Defaults to 10 |
Example
- type: pi-hole-top-queries
options:
hostname: https://pi-hole.local
apiKey: xxxxxxxxxxxxxxxxxxxxxxx
Recent Traffic
Shows number of recent traffic, using allowed and blocked queries from Pi-Hole
Options
Field | Type | Required | Description |
---|---|---|---|
hostname |
string |
Required | The URL to your Pi-Hole instance |
Example
- type: pi-hole-traffic
options:
hostname: https://pi-hole.local
Stat Ping Statuses
Displays the current and recent uptime of your running services, via a self-hosted instance of StatPing
Options
Field | Type | Required | Description |
---|---|---|---|
hostname |
string |
Required | The URL to your StatPing instance, without a trailing slash |
Example
- type: stat-ping
options:
hostname: http://192.168.130.1:8080
Dynamic Widgets
Iframe Widget
Embed any webpage into your dashboard as a widget.
Options
Field | Type | Required | Description |
---|---|---|---|
url |
string |
Required | The URL to the webpage to embed |
frameHeight |
number |
Optional | If 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
Field | Type | Required | Description |
---|---|---|---|
html |
string |
Optional | HTML contents to render in the widget |
script |
string |
Optional | Raw JavaScript code to execute (caution) |
scriptSrc |
string |
Optional | A URL to JavaScript content (caution) |
css |
string |
Optional | Any stylings for widget contents |
Example
- type: embed
options:
scriptSrc: https://cdn.speedcheck.org/basic/scbjs.min.js
html: |
<div id="sc-container">
<div id="sc-branding" class="sc-bb">
<a target="_blank" href="https://www.speedcheck.org/">
<img src="https://cdn.speedcheck.org/branding/speedcheck-logo-18.png" alt="Speedcheck"/>
</a>
</div>
</div>
Or
- type: embed
options:
css: '.coinmarketcap-currency-widget { color: var(--widget-text-color); }'
html: '<div class="coinmarketcap-currency-widget" data-currencyid="1" data-base="USD" data-secondary="" data-ticker="true" data-rank="true" data-marketcap="true" data-volume="true" data-statsticker="true" data-stats="USD"></div>'
scriptSrc: 'https://files.coinmarketcap.com/static/widget/currency.js'
API Response
Directly output plain-text response from any API-enabled service
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: 6e29c7d514cf890f846d58178b6d418f
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.
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
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.