@blumepage/dicebear-flowers

Three generations of flower avatars in one package:

• v1 — the original configurable DiceBear flower style.
• v2 — species-based crowns with two-level project/conversation seeding. It works both as a DiceBear style and as a standalone SVG API.
• v3 — the cohesive final-pass flower set: approved species silhouettes, one shared outline system, normalized project framing, and explicit species-specific geometry parameters.

From package 3.0.0, the package root is v3. Explicit /v1 and /v2 entry points remain available for applications that need the earlier renderers.

Install

npm install @dicebear/core @blumepage/dicebear-flowers

Versioned entry points

| Import | API | | --- | --- | | @blumepage/dicebear-flowers | v3 current API | | @blumepage/dicebear-flowers/v1 | explicit v1 DiceBear style | | @blumepage/dicebear-flowers/v2 | v2 DiceBear style and standalone renderers | | @blumepage/dicebear-flowers/v3 | final-pass v3 DiceBear style and standalone renderers |

v3

v3 keeps the v2 two-seed model, but replaces the crown layer with the final curated system. Project crowns are always centered in the same frame, use the flower head for sizing, and receive only a very short connector when a side-profile flower needs one. Seeded size and position variation are reserved for conversation settings—not project crowns.

import {
  projectAvatar,
  conversationAvatar,
} from '@blumepage/dicebear-flowers/v3';

const project = projectAvatar('my-project', {
  species: { allow: ['dahlia'] },
  lineWidth: { min: 1.15, max: 1.15 },
  dahliaStyle: { allow: ['waterlily', 'ball'] },
  ringCount: { min: 3, max: 5 },
  twoTone: true,
});

const conversation = conversationAvatar('my-project', 'conversation-7', {
  crown: { species: { allow: ['dahlia'] } },
  setting: { bgPattern: { allow: ['rings', 'wedges', 'bands'] } },
});

v3 parameter model

v3 keeps the v2 parameter shapes:

• Choice<T> — { allow?: T[], deny?: T[] } for curated enums and colors.
• Span — { min?: number, max?: number }; equal values lock a number.
• boolean | undefined — an explicit value locks the flag; undefined uses the deterministic seeded default.

The system has four layers:

1. Identity — species, palette, center treatment, and two-tone behavior.
2. Shared drawing grammar — lineWidth, petalLength, petalWidth, centerRatio, and irregularity work across the species that support them.
3. Species geometry — named styles plus biologically meaningful counts, proportions, and detail controls.
4. Setting — v2's conversation-seeded stems, bouquets, foliage, harmonious backgrounds, and background-pattern parameters.

The default lineWidth is fixed at 1.15, so randomly generated species feel drawn by the same hand. Callers can set it from 0.8 to 1.7; the recommended production range is 0.95–1.35.

Shared v3 crown parameters

| Parameter | Range / values | Meaning | | --- | --- | --- | | species | 14 species | Approved flower renderer | | petalColor / centerColor | hex choices | Curated colors by default; custom colors supported | | petalVariation | boolean | Small deterministic variation around the base color | | twoTone | boolean | Enables the species' approved secondary-color placement | | lineWidth | 0.8–1.7 | Shared visible petal outline; default 1.15 | | petalCount | species-clamped | Petals, rays, or repeated major units | | petalLength | 0.78–1.18 | Multiplier around the approved silhouette | | petalWidth | 0.78–1.32 | Multiplier around the approved silhouette | | centerRatio | 0.08–0.44 | Center radius relative to the common head radius | | irregularity | 0–0.16 | Restrained organic variation; default stays subtle | | rotation / spread | v2-compatible | Explicit overrides; project defaults remain canonical |

Species-specific v3 parameters

| Species | Style values | Geometry controls | | --- | --- | --- | | Daisy | final A11 family | petalCount 14–24, petalLength, petalWidth, centerRatio, irregularity | | Sunflower | full, burgundyRing | petalCount 22–30, petalWidth, centerRatio | | Rose | approved current family | petalCount 7–12, ringCount 2–3, twoTone | | Tulip | classic, cup, bud, sculpted | tulipOpenness, tulipPetalShape, heightWidthRatio .85–1.15, twoTone | | Poppy | classic, corn | petalCount 4–6, centerRatio, blackBlotch | | Forget-me-not | approved current family | fixed five petals, petalWidth, centerRatio, subtle twoTone | | Bluebell | soft, sculpted | bellCount 3–7, racemeArc .15–.70, twoTone | | Lantana | dense H11-derived dome | floretCount 30–60, clusterSpread, floretSize, colorZones 1–3 | | Lily | approved current family | fixed six tepals, petalWidth, spots, twoTone | | Cosmos | approved broad-ray family | petalCount 8–10, petalWidth, notchDepth, centerRatio | | Anemone | classic, coronaria | petalCount 6–8, centerRatio, stamenDensity 8–22 | | Dahlia | classic, waterlily, ball | ringCount 3–5, petalWidth, colorPlacement, twoTone | | Bellflower | short, medium, tall | bellflowerFlare, bellflowerRim, mouthDepth; connector stays fixed | | Marigold | classic, frenchBicolor | ringCount 3–5, density 20–48, ruffle, twoTone |

The v3 DiceBear entry exposes the same controls as arrays, following DiceBear's style convention. Numeric arrays become spans; enum and color arrays become allow-lists.

import { createAvatar } from '@dicebear/core';
import { style } from '@blumepage/dicebear-flowers/v3';

const svg = createAvatar(style, {
  seed: ['conversation-7'],
  projectSeed: 'my-project',
  species: ['bluebell'],
  bluebellBellType: ['soft', 'sculpted'],
  bellCount: [3, 7],
  lineWidth: [1.15],
}).toString();

v1 with DiceBear

import { createAvatar } from '@dicebear/core';
import { style } from '@blumepage/dicebear-flowers/v1';

const svg = createAvatar(style, { seed: 'rosie' }).toString();

v2 with DiceBear

import { createAvatar } from '@dicebear/core';
import { style } from '@blumepage/dicebear-flowers/v2';

const svg = createAvatar(style, {
  seed: 'conversation-1',
  projectSeed: 'my-project',
  species: ['rose', 'tulip'],
}).toString();

DiceBear's seed drives the setting by default. Set projectSeed to keep the same crown across different avatar seeds. Set mode: ['project'] to render only the crown tile. Project crowns use a canonical centered 100% frame with zero rotation unless explicitly overridden. Every crown receives one flat deterministic companion-color tile, with a contrast guard for pale or unusually bright petals.

v2 standalone

import {
  projectAvatar,
  conversationAvatar,
} from '@blumepage/dicebear-flowers/v2';

const project = projectAvatar('my-project');
const convA = conversationAvatar('my-project', 'conversation-1');
const convB = conversationAvatar('my-project', 'conversation-2');
// convA and convB show the same flower in visibly different settings.

The standalone v2 renderer has no runtime dependencies and returns pure, deterministic SVG strings.

v2 parameter model

Every tunable uses one of three shapes:

• Choice<T> for enums: { allow?: T[], deny?: T[] }. If allow is present, only those values are used (whitelist). Otherwise the full curated pool minus deny is used (blacklist).
• Span for numbers: { min?, max? }. Omitted sides keep the curated default; min === max locks the value.
• plain boolean | undefined for flags: undefined means the seeded default.

conversationAvatar('proj', 'conv', {
  crown: {
    species: { allow: ['rose', 'tulip'] },   // only roses and tulips
    twoTone: false,
  },
  setting: {
    bgTone: { deny: ['bold'] },              // avoid the richest backgrounds
    flowerCount: { allow: [1] },             // never bouquets
    zoom: { min: 90, max: 110 },
  },
});

Crown params (from the project seed)

| Param | Shape | Notes | | --- | --- | --- | | species | Choice<SpeciesId> | 14 species, see below | | petalColor | Choice<string> | hex without #; whitelist may contain custom colors | | petalVariation | boolean? | gentle deterministic variation around curated base colors; explicit petalColor.allow stays exact unless this is true | | centerColor | Choice<string> | custom combos are luminance-guarded | | centerStyle | Choice<'dot'\|'ring'\|'dotted'> | | | tulipOpenness | Choice<'closed'\|'open'> | tulip-only; sampled by project seed by default | | tulipPetalShape | Choice<'rounded'\|'sharp'> | tulip-only; combines independently with openness | | bellflowerFlare | Choice<'narrow'\|'wide'> | bellflower-only; keeps the same stem attachment point | | bellflowerRim | Choice<'soft'\|'ruffled'> | bellflower-only; broad lobes or denser scallops | | petalCount | Span | clamped to per-species bounds | | rotation | Span (0–359°) | default 0; explicit override only | | spread | Span (88–108 %) | default 100%; explicit petal-size override | | twoTone | boolean? | variegated petals |

Setting params (from the conversation seed)

| Param | Shape | Notes | | --- | --- | --- | | stem / background | boolean? | default on | | flowerCount | Choice<number> (1–3) | defaults to 25% single, 42% double, 33% triple | | zoom | Span (70–140 %) | bouquet-only; singles stay centered at 100% | | stemStyle | Choice<'straight'\|'bent'\|'wavy'> | | | stemColor / leafColor | Choice<string> | default: greens matched to bg luminance | | leafShape | Choice<'thin'\|'almond'\|'round'\|'strap'\|'twin'> | | | leafCount | Choice<number> (0–2) | | | leafSize | Span (60–120 %) | | | leafAngle | Span (−45..45°) | | | bgLightness | Choice<'light'\|'mid'> | filters the tone pool by lightness class; combines with bgTone | | bgTone | Choice<BgTone> | see tones below | | bgColorMode | Choice<'tonal'\|'harmonic'> | tonal shades, or two harmonic anchors with every additional color derived from one of them | | bgPattern | Choice<BgPattern> | solid bands wedges dots corner gradient rings checker | | bgAngle | Span (0–179°) | pattern angle | | bgCount | Choice<number> | rings are clamped to 1–3; other patterns use 2–8 and default to 2, 4, 6, or 8 | | bgCenterX / bgCenterY | Span (0–100) | center for rings, wedges and pattern phase | | bgScale | Span (50–160 %) | ring size, checker/dot scale, gradient spread; wedges may grow but never shrink below full-tile coverage | | bgColor | string[] | full base override; siblings derived, contrast-guarded |

Background tones

A conversation with no explicit background color constraints uses the companion carousel by default. It rotates through eight broad hue relationships around the locked flower color, pairing each direction with a different pastel intensity. This gives conversations belonging to the same project much stronger color distinction while every result remains relative to the project's petal hue. The default is tonal: any third or later pattern color is therefore only a shade variation of the first.

Setting bgTone, bgLightness, or bgColor opts into the corresponding controlled recipe below. bgColorMode: harmonic can also be combined with the carousel when a consumer deliberately wants two hue anchors.

A background is one flat tone — a self-contained recipe with its own hue source. The three companion tones (tint, soft, bold) each sample a slice of one shared intensity curve (pale near-white → rich mid-tone); the slices overlap, so the whole set sweeps continuously with no gap. That continuity is what makes intensity look gradual across a grid instead of jumping between "barely tinted" and "loud". The palette is all light and mid by design — there are no dark tones.

Each tone belongs to one lightness class (light, mid), and bgLightness filters the tone pool through that map — so "light only" is one constraint, and it can't contradict a tone the way an independent mode flag could. An explicit bgTone whitelist wins if the two conflict.

| Tone | Class | Recipe | | --- | --- | --- | | tint | light | companion hue, pale end of the intensity curve | | wash | light | pale wash of the petal's own hue | | beige | light | warm Blume neutral through pale sand | | garden | light | curated scenic tone (sky, sage, cream, blush, mint, lilac, sand) | | soft | mid | companion hue, middle of the intensity curve | | bold | mid | companion hue, rich end (saturation-capped, never within 40° of the petal hue) |

Companion hues are hand-tuned per petal hue band (red→sage/teal, yellow→lavender/sky, blue→butter/peach, …). Quality guards apply everywhere: chartreuse mid-tones are pulled back to butter, mid-lightness magenta is desaturated, curated tones too close in hue to the petal are filtered out, and a contrast guard nudges the background luminance away from the flower until it reads. Default patterns still favor quieter solid, gradient, corner, ring, and dot treatments, but parallel bands and radial wedges, rings, and checker fields now occur at restrained weights. Background counts literally produce two, four, or six sections, with eight-section variants kept rarer. Radial origins and motif size are independently seeded and can be locked with bgCenterX, bgCenterY, and bgScale. The default palette keeps enough chroma to remain visibly distinct in compact list avatars. Harmonic color mode lets patterns combine two or, in larger motifs, three companion hues. Most pairs stay analogous—such as mint–lime or aqua–sky—while some use a wider split-complementary relationship. Tonal mode keeps single-hue shading.

Species

| Species | Look | | --- | --- | | daisy | many slim petals, dotted seed center | | sunflower | two layered pointed-petal rings, big seed head | | rose | top-down concentric rings (2–3), spiral/bud/whorl hearts | | tulip | side-profile cup with a short project-tile connector, varied height/flare | | poppy | broad overlapping petals, dark center with stamens | | forgetmenot | five round petals, yellow eye | | bluebell | experimental nodding raceme of scalloped bell blooms | | lantana | experimental multicolor cluster of tiny four-lobed florets | | lily | long pointed petals with midribs | | cosmos | wide notched petals | | anemone | broad petals, big dark center ringed by stamens | | dahlia | pom-pom of three pointed-petal rings | | bellflower | side-profile bell with a scalloped mouth and short project-tile connector | | marigold | dense ruffled rings of scalloped petals |

Species keep their recognizable color families at full weight, while curated cross-species colors occur at lower weight. This makes combinations such as purple or blue sunflowers possible without making classic yellow/orange sunflowers uncommon. Custom petalColor allow-lists still override the pool.

Lower-level API

import {
  createCrown,     // (projectSeed, CrownParams?) => CrownSpec
  createSetting,   // (crown, conversationSeed, SettingParams?) => SettingSpec
  renderCrown,     // (crown, { tile?, tileColor? }?) => svg
  renderSetting,   // (spec) => svg
} from '@blumepage/dicebear-flowers/v2';

Preview panel

npm install
npm run preview:install
npm run preview   # http://localhost:5180

Switch between conversation and project modes, lock a project seed to see one flower across many conversation settings, and switch the avatar size (16–100 px). Every param is editable: enum chips cycle neutral → allow → deny (matching the whitelist/blacklist semantics), spans use min/max sliders, flags are default/on/off. State persists in localStorage.

License

MIT