Flungies

• usr_8f3k2
• usr_01hzx3k9qv
• usr_7d1c0b
• usr_a
• usr_b
• flung
• creator
• mem_1
• mem_2
• org_demo
• ws_northwind
• 42

TL;DR

What a Flungie is

Flung's mark (G9) is a speech bubble thrown across the frame. A Flungie is that bubble as a character: a plush, felted body with a tail, caught mid-throw, leaning into the throw.

• The body is the bubble: a soft superellipse with a wedge-shaped tail at its lower back.
• Two speed lines trail behind it, in two of the brand's colours (peach over sky is the brand pair).
• A face sits toward the front of the body, the way it is travelling.
• An accessory is chosen from a creator-themed set: headphones, caps, a beanie, glasses, a party hat, an antenna, a bow, a ring light, a crown, a megaphone, a pencil and a paper plane.
• A disc behind it is a soft tint on light pages and a deep tone on dark ones. A square tile (variant: 'square') and no ground at all ('bare') are the other variants.

By default the Flungie flies right, with its tail on the left, as the mark does. About a third of Flungies are mirrored. A mirrored Flungie is the same drawing, flipped.

Try it

Type any id to see its Flungie, at every size it simplifies or adds detail at, and the traits it picked. It opens on usr_8f3k2.

Install

npm install @flung.dev/flungies

Use

1import { flungie, toDataUri, traits, render } from '@flung.dev/flungies'2
3el.innerHTML = flungie(user.id, { size: 32, theme: 'dark' })    // an SVG string4img.src = toDataUri(flungie(user.id, { size: 64 }))               // or a data: URI5render(traits(user.id, { accessory: 'crown' }), { size: 128 })    // overrides win over the seed

Seed with a stable ID, such as a user ID, rather than an email or a name that may change.

On a server

The core needs no DOM, so a Worker can serve Flungies as images. A seed always gives the same drawing, so the response can be cached forever.

1import { flungie } from '@flung.dev/flungies'2
3export default {4  fetch(request: Request): Response {5    const url = new URL(request.url)6    const id = url.searchParams.get('id') ?? ''7    const size = Math.min(512, Math.max(16, Number(url.searchParams.get('size')) || 64))8    return new Response(flungie(id, { size }), {9      headers: { 'content-type': 'image/svg+xml', 'cache-control': 'public, max-age=31536000, immutable' },10    })11  },12}

Each SVG's internal ids come from a counter by default. When a server renders a Flungie into HTML that a browser then hydrates, pass the id option (flungie(id, { size, id: 'avatar-1' })) so both sides write the same markup. The React component does this for you with useId.

React

1import { Flungie } from '@flung.dev/flungies/react'2
3<Flungie seed={user.id} size={32} />4<Flungie seed={user.id} size={240} theme="dark" animated />

With animated and a size of 160 or more, the component shows the SVG first, then loads @flung.dev/flungies/gl and swaps in the WebGL hero. Below 160 px, it is always the SVG. The component renders on a server and hydrates without a mismatch.

WebGL hero

1import { mountFlungieGL } from '@flung.dev/flungies/gl'2
3const hero = mountFlungieGL(el, user.id, { size: 320, theme: 'light' })4hero.setTheme('dark')5hero.setSize(240)6hero.dispose()   // stops the loop, releases the GL context and empties el

The hero animates only while it is on screen and the page is visible. Under prefers-reduced-motion it draws one still frame. Without WebGL2, or if the context is lost, it shows the SVG Flungie, and hero.webgl is false.

Custom element

1import { defineFlungie } from '@flung.dev/flungies/element'2defineFlungie()   // registers <flung-ie>; defineFlungie('my-avatar') uses another name

1<flung-ie seed="usr_8f3k2" size="40" theme="dark"></flung-ie>2<flung-ie seed="usr_8f3k2" size="240" animated></flung-ie>

The element takes the attributes seed, size, theme, variant, salt and animated.

Options

For other products, these options change which Flungie a seed gives. With all of them unset, a seed gives exactly the Flungie it gives on Flung.

1flungie(user.id, { salt: 'acme', accessories: { exclude: ['crown', 'halo'] } })2traits(user.id, {}, { salt: 'acme' })   // traits(seed, overrides, config)

Size tiers

A Flungie is drawn for its size: small ones drop detail that would turn to noise, large ones gain a felt texture.

The stability promise

A seed's Flungie never changes. People recognise theirs, so a drawing that moved would be a breaking change for every one of them, however much better it looked. Version 1 of the drawing is frozen, and every release is checked against a fixed set of seeds and the exact SVG each one draws. A change that has to alter an existing Flungie ships behind a new version you opt into, and the default stays where it is.

What does change a Flungie is yours to choose: salt, palette and accessories make a set of your own, and overrides sets a trait outright. With none of them, a seed gives exactly the Flungie it gives on Flung.

Traits

Every trait draws from a stream of its own, seeded by the id, so overriding one trait never changes another. The chance is how often a seed picks the option; overrides picks it outright.

Accessories

The creator set. An accessory's colour is picked from a list of its own, the first that stands clear of the body (and, for one above the head, of both themes' discs).

Bodies

The bubble, as a soft superellipse with a tail, in six builds.

Colours

The body colour. Each one sits on a disc chosen for it, a pale tint on a light page and a deep tone on a dark one.

Eyes

Mouths

Speed lines

The two lines behind the body, upper and lower. Peach over sky is the brand pair.

Side

Which way the Flungie flies. By default it flies right with its tail on the left, as the mark does.

Blush

Rosy cheeks, on or off, picked by the seed.

Accessibility

Every Flungie is an image with a name: the SVG carries role="img" and an aria-label that says what it shows, such as "Flungie avatar: Ocean wobbly with crown", and describe() returns the same words.

Next to the person's name, a Flungie repeats what the name says. There, hide it from screen readers: aria-hidden="true" on the element that holds it, or an empty alt on an <img> with a data: URI.

The animated hero breathes and blinks only while it is on screen and the tab is visible, and under prefers-reduced-motion it draws one still frame. Below 160 px the React component always draws the still SVG.

Also exported

• TRAITS, every trait with its options, for pickers.
• combinations(), which returns 907,200 discrete trait sets.
• The tables COLOURS, DISCS, SHAPES, EYES, MOUTHS, ACCESSORIES, ACC_COLOURS, LINE_PAIRS and SIDES.
• colours() and geometry(), for renderers of your own.
• toSvgElement(svg), which parses an SVG string into an element to append, for pages that may not assign innerHTML.
• describe(), the accessible name, which every SVG also carries as its aria-label.
• The colour helpers contrast, distance, luminance and mix.

See also