Linkshuffle Docs

2/4/2023

Figure out how Linkshuffle works.

Back
Note
This is the more technical documentation of Linkshuffle. Currently, there isn't an easy way to use this if you're not knowledgeable with Javascript.

Quickstart

Wanna make your own list of links? You should change the ls-list configuration property by directly modifying the file. Soon, I would like to make a generator.

Modifying Linkshuffle

There are three ways to modify Linkshuffle's configuration.

Query parameters

Great for easily modifying the look of Linkshuffle when embedding it. Simply add the configuration to the URL like so:
https://dabric.xyz/linkshuffle.min.html?lsstyle-foreground=lime&lsstyle-background=darkslategrey

Attributes

Warning
You have to host Linkshuffle yourself. If you hotlink from my website, it won't do anything.
Great for dynamically modifying the configuration with JavaScript. Simply add the configuration using data- attributes:
  • js
<iframe src="https://dabric.xyz/linkshuffle.min.html" frameborder="0" title="linkshuffle"></iframe>

<script>
	const frame = document.querySelector("iframe");
	let hue = 0;

	setInterval(() => {
		hue += 5
		hue %= 360
		const color = `hsl(${hue}deg, 100%, 50%)`;
		frame.setAttribute("data-lsstyle-foreground", color)
		frame.setAttribute("data-lsstyle-overlay-foreground", color)
		frame.setAttribute("data-lsstyle-outline-color", color)
	}, 100);
</script>

Directly modifying the file

Great for distributing your own collection of links. Download the unminified version, and scroll to the bottom of the HTML file. You'll want to add a script tag:
  • html
...
					}
					window.dispatchEvent(new CustomEvent("ls-loaded"));
				})();
			});
		</script>

		<script>
			// Here.
		</script>
	</body>
</html>
In your script tag, listen for the ls-loaded event on the window. Here, use the setConfig() function exposed in the global scope to modify Linkshuffle's config.
  • html
<script>
	window.addEventListener("ls-loaded", () => {
		setConfig("ls-showtitle", "false");
		setConfig("ls-list", "url!https://example.com/links.json");

		setConfig("lsstyle-foreground", "black");
		setConfig("lsstyle-background", "white");
	});
</script>

Configuration

Linkshuffle has two types of configuration: style and data. The main difference is how they're managed. Style uses CSS variables, while data uses JavaScript. Both can be easily modified, as shown above.

Data configuration

ls-delay

The amount of time in milliseconds between links. Set it to 0 to disable automatically switching.
Default: 10000 (10 seconds)

ls-showrandombutton

A Linkshuffle embed, highlighting the random button.
Whether or not to show the random button. The random button lets the user switch to another link upon click.
Default: true

ls-showtitle

A Linkshuffle embed, highlighting the link title.
Whether or not to show the title of the link at the top left upon hover.
Default: true

ls-list

The list of links in JSON. View the format here.
You can also provide a URL for Linkshuffle to fetch the JSON from. Give the link with url! at the start. For example: url!https://example.com/links.json.
Default: null (no links)

ls-brandname

A Linkshuffle embed, highlighting the linkshuffle watermark link.
The text for the bottom right Linkshuffle watermark.
Default: linkshuffle

ls-brandnamesmall

A Linkshuffle embed, highlighting the tiny Linkshuffle watermark link.
Like ls-brandname, but for when the mouse isn't hovering.
Default: lnkshfl

ls-brandlinklocation

A Linkshuffle embed, highlighting the linkshuffle watermark link.
Where the bottom right Linkshuffle watermark goes to.
If you change this, it would be nice if you gave me some credit somewhere other than the MIT license. Like a "Powered By Linkshuffle" or something on the page the link goes to?
Default: https://dabric.xyz/post/linkshuffle/

ls-anchorbottom

A Linkshuffle embed, with the bottom menu anchored.
Anchors the bottom menu so it doesn't obscure the image. The height is set by lsstyle-anchor-height.
Default: false

ls-removeonerror

Temporarily removes an image when it fails to load, or the entire link if none of the images work.
Default: true

ls-compatibilityredirect

Redirects to an earlier version of Linkshuffle if the link list format is too old for it. This only happens when the link list is supplied with url!.
Default: true if detected to be hosted on my website, false if not.

Style configuration

lsstyle-background

A Linkshuffle embed showing off the background color.
Shown here in red.
Default: black

lsstyle-foreground

A Linkshuffle embed showing off the overlay background color.
Shown here in red.
The foreground color.
Default: white.

lsstyle-overlay-background

A Linkshuffle embed showing off the overlay background color.
Shown here in red.
The background color for the overlays, which are the things that go on top of the image.
Default: black

lsstyle-overlay-foreground

A Linkshuffle embed showing off the overlay foreground color.
Shown here in red.
The foreground color for the overlays, which are the things that go on top of the image.
Default: white

lsstyle-outline-color

A Linkshuffle embed showing off the outline color.
Shown here in red.
The color used for outlines.
Default: #808080

lsstyle-title-bar-shift

How much the title bar slides in upon hover.
Default: 25px
Note
On systems with reduced motion turned on, this option is forced to zero.

lsstyle-menu-bar-shift

How much the menu bar slides in upon hover. This may make sense to set to zero when there is no short brand name provided.
Default: 25px
Note
On systems with reduced motion turned on, this option is forced to zero.

lsstyle-font

The font.
Default: sans-serif

lsstyle-font-size

The font size.
Default: 1em

lsstyle-padding

The amount of padding (empty space).
Default: 5px

lsstyle-outline-thickness

How thick the outlines are. Set it to 0px to get rid of them.
Default: 2px

lsstyle-border-radius

How much corners are rounded off.
Default: 5px

lsstyle-anchor-height

The height of the bottom menu when ls-anchorbottom is set to true.
Default: calc(1em + var(--padding) * 2)

Hosting

You can download Linkshuffle for your own use to get around cross-site madness. Just keep in mind of the MIT license at the top of the file.
A list of links are in JSON, with the following format. Everything is optional, but it's highly recommended to fill them all out.
  • json
// linkshuffle has basic json comment support.
// use `//`. only an entire line may be a comment.
// so, this will result in a syntax error:
//     "name": "dabric", // comment
// but this wont:
//     // comment
//     "name": "dabric",
{
	// the version of this format. if linkshuffle detects
	// an older version, it'll automatically redirect to
	// said older version if `ls-compatibilityredirect`
	// is true.
	"version": 1,
	"links": [
		// an example link. it'll be picked at random.
		{
			// the version of this format for this specific
			// link. you don't need this when you're
			// directly putting in links like this; it's
			// intended for when you reference a url.
			"version": 1,

			// the name of the link.
			// - will be shown on hover, unless ls-showtitle
			//   is set to false.
			// - will also be shown in place of the image if
			//   there isn't one, or if it fails to load.
			"name": "dabric",

			// the images to use. it'll be picked at random.
			"images": [
				// an example image. you can have
				// an unlimited number of them.
				{
					// the link to the image.
					"src": "https://dabric.xyz/dabric.png",

					// the alt text for the image.
					"alt": "a short tv-head robot."
				}
			],

			// the link.
			"url": "https://dabric.xyz"
		},
		// you can also give a url to a link like this.
		"https://dabric.xyz/me.json"
	]
}