ilicon
v1.0.1
Published
A small package for fetching site favicons & nicely displaying them inline.
Downloads
3
Maintainers
Readme
iLicon
A small package for fetching site favicons & nicely displaying them inline.
Quick Demo
An embedded github gist, containing some anchor tags:
After calling iLicon
with 0
config on the same page:
Table of Contents
Features
Automatically fetches favicons for links and displays them inline. With plenty of configuration options and some potential future features.
Installation
iLicon
installation should hopefully be pretty straight forward, but if you run into any issues let me know.
Node
For usage in bundlers, note that iLicon
is currently client side only, more info below.
# npm
npm install ilicon
# yarn
yarn add ilicon
# pnpm
pnpm add ilicon
CDN
<script src="unpkg/jsdelivr link once published"></script>
Usage
The automatic, no-config version of iLicon
is pretty simple, just import it and call it with no arguments. This will:
- Find all links on the page
- Insert a small favicon of the link in the
href
before the text of each anchor tag
import { iLicon } from 'ilicon';
...
// Somewhere browser-side:
iLicon({
// Options
});
Options
NOTE: All options are optional!
| Option | Type | Default | Description |
| -------------------- | ------------------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| root
| HTMLElement
| document.body
| The element to start traversal from. By default iLicon
will search the whole document, but if that's not needed you can set the starting element, from which iLicon
will search from, including all descendants. |
| skipIDs
| string[]
| undefined
| An array of strings representing element IDs to skip checking links for. Skipping an element will also skip all descending elements, so this will likely dramatically improve performance. |
| skipClasses
| string[]
| undefined
| Similar to the above skipIDs
this is an array of strings representing element classes to skip checking links for. Skipping an element will also skip all descending elements, so this will likely dramatically improve performance. |
| injectiLiconStyles
| boolean
| true
| If true
will call a funtion injecting a <style>
tag with about ~10
lines into the page's <head>
if it doesn't already exist. This will not create multiple style tags if called more than once. See default styles & classes below. |
| wrapperClass
| string
| ilicon_wrapper
| Class applied to the wrapping <a>
tag, used for basic alignment. |
| imgClass
| string
| ilicon_img
| Class applied to the generated <img>
tag, used for sizing & basic alignment. |
| setIcons
| { domain: string, icon: string }[]
| undefined
| An array of objects containing the domain name (ex: google.com) and the specified icon to use for that domain (ex: /some_icon.png or .ico or base64) instead of using duckduckgo's supplied favicon. |
| position
| 'start' \| 'end'
| 'start'
| Decides whether the favicon is inserted before or after the link text. |
| transformer
| Function
| defaultTransformer
| The transformer function, expanded below is what every found anchor element is passed to. This is what takes the anchor tag on the page and spits out the version with a favicon. |
| target
| string[]
| undefined
| Experimental. Instead of the default behavior giving iLicon
a list of links via the target
parameter will return the duckduckgo favicon links for all given URLs. |
Default Styles
.ilicon_wrapper {
display: inline-flex;
align-items: center;
height: 1cqmax;
}
.ilicon_img {
width: 100%;
height: 100%;
margin: 0 0.25rem;
}
Transformer
This is the current default transformer:
function defaultTransformer(
element: HTMLElement,
url: string,
pos = 'start',
wrapperClass = 'ilicon_wrapper',
imgClass = 'ilicon_img'
) {
const isAnchor = element.nodeName === 'A';
if (isAnchor) {
element.classList.add(wrapperClass);
const img = document.createElement('img');
img.classList.add(imgClass);
img.src = url;
if (pos === 'start') {
element.insertAdjacentElement('afterbegin', img);
} else {
element.insertAdjacentElement('beforeend', img);
}
}
}
Breakdown:
element
is the current anchor tag we're working withurl
is the url of the favicon to use (favicons are obtained before transforming anchor tags)pos
is the position of the favicon relative to the anchor tag's text, either'start'
or'end'
for before or after respectivelywrapperClass
is the class applied to the wrapping<a>
tag, used for basic alignmentimgClass
is the class applied to the generated<img>
tag, used for sizing & basic alignmentisAnchor
is a boolean representing whether the current element is an anchor tag or not- This is just a quick check to make sure we're working with an anchor tag, and later on will be used to work with non-anchor tags
If you want to use your own transformer, you can pass it into iLicon
via the transformer
option. It will be called with the same arguments as the default transformer, and you can use the default transformer as a reference for how to write your own. Ex:
iLicon({
transformer: (element, url, pos, wrapperClass, imgClass) => {
// Do something with the element
},
});
Contributing
I've not managed an open-source project before, so I'm not sure what the best way to go about this is. But if you have any suggestions or want to contribute, feel free to open an issue or PR and I'll take a look!
Future considerations / Potential features
- [ ] Tests
- Currently just been testing in a browser with the dist but some more formal and automated tests would be nice
- [ ] Add support for links within non anchor tags
- [ ] Add support for links within anchor tags that don't have an href attribute
- [ ] Add support for links within anchor tags that have an href attribute but no value?
- [ ] Fix the cors issue and add an option to 'check' icons before displaying them & fallback to a default icon if they don't exist
- [ ] Async version that does check for the default bad icon from ddg and will swap to google if it doesn't exist
- [ ] Mini version that's the same as normal but won't grab all links, instead will just take an element and link and act on that
- [ ] This would also cover SSR if I have it just return the resulting element
- [ ] Importable css instead of injected
- [ ] Support relative links