candle_reader

An interactive candle reading-light widget for Flutter.

Wrap any widget with CandleLight to get a warm, spring-following animated flame that dims everything around it. Pinch to resize the pool of light, pinch hard to blow the flame out (with rising smoke wisps), tap to relight.

Works over any child: plain text, PageView, ListView, Image, PdfView, or your own custom reader.

Features

• Layered teardrop flame with organic flicker and sway
• Spring-damped follow physics (not a lazy lerp)
• Pinch-to-resize the light pool; pinch below threshold extinguishes
• Extinguish animation: flame curls into an ember, rising smoke wisps with sine-curl drift and air drag
• Tap to relight
• Five built-in FlamePalettes (warm, blue, green, red, violet) plus FlamePalette.fromColor(...) for any hue you want
• Three interaction modes so the widget composes cleanly with scrollable children
• Programmatic control via CandleLightController
• Reduced-motion aware (respects MediaQuery.disableAnimations)
• Screen-reader friendly
• Zero dependencies beyond Flutter itself

Install

dependencies:
  candle_reader: ^0.1.0

Quick start

import 'package:candle_reader/candle_reader.dart';

CandleLight(
  child: Text('Once upon a time...'),
)

Over a scrollable child

The default (twoFinger) mode is tuned for readers: one finger scrolls the list, two fingers move and resize the candle, long-press-then-drag lets a single finger pick the candle up, and tap relights it — the iOS pinch-while-scrolling model.

CandleLight(
  child: ListView(
    children: [/* your pages */],
  ),
)

If your content doesn't need to scroll and you want single-finger drag to move the flame, opt into grab:

CandleLight(
  interaction: CandleLightInteraction.grab,
  child: Text('Once upon a time...'),
)

Flame color

Pick a preset:

CandleLight(
  palette: FlamePalette.blue,   // or .warm (default), .green, .red, .violet
  child: myReader,
)

Or derive a palette from any single color — outer/mid/inner/core are generated by darkening and lightening it:

CandleLight(
  palette: FlamePalette.fromColor(Colors.pinkAccent),
  child: myReader,
)

Or build one by hand for full control:

CandleLight(
  palette: const FlamePalette(
    outer: Color(0xFF1E5FD6),
    mid:   Color(0xFF3E88FF),
    inner: Color(0xFFA8D8FF),
    core:  Color(0xFFE8F6FF),
    ember: Color(0xFF1E5FD6),
  ),
  child: myReader,
)

The pool's warm glow follows the palette automatically. If you want a different glow color than the flame body, set warmTint explicitly.

Programmatic control

final controller = CandleLightController();

CandleLight(
  controller: controller,
  interaction: CandleLightInteraction.controlled,
  child: myReader,
);

// Later:
controller.position = Offset(200, 400);  // flame animates there
controller.radius = 220;
controller.blowOut();
controller.relight();

Reacting to events

CandleLight(
  onExtinguished: () => analytics.log('candle_out'),
  onRelit: () => analytics.log('candle_lit'),
  onPositionChanged: (p) => bookmarkService.setCursor(p),
  onRadiusChanged: (r) => prefs.setLastRadius(r),
  child: myBook,
)

Parameters

Parameter	Type	Default	Notes
child	Widget	required	The content the candle illuminates
interaction	CandleLightInteraction	twoFinger	grab / twoFinger / controlled
controller	CandleLightController?	null	Drive or observe the candle externally
initialRadius	double	160	Light pool radius at mount, in px
minRadius	double	8	Pinch floor while still lit
maxRadius	double	560	Pinch ceiling
extinguishRadius	double	26	Pinch below this → blow out
relightRadius	double	70	Pinch above this (while out) → relight
initialPosition	Offset?	null	Defaults to center of the widget
dimColor	Color	#050505	Painted outside the pool
warmTint	Color?	null	Additive glow inside the pool. When null, follows palette.mid.
palette	FlamePalette	FlamePalette.warm	Per-layer flame colors. See "Flame color".
enableHaptics	bool	true	System haptics on blow-out / relight
onExtinguished	VoidCallback?	null	Fires on blow-out
onRelit	VoidCallback?	null	Fires on relight
onPositionChanged	ValueChanged<Offset>?	null	Fires on user drag
onRadiusChanged	ValueChanged<double>?	null	Fires on user pinch
semanticLabel	String	'Candle reading light'	Announced by screen readers

Interaction modes

CandleLightInteraction.twoFinger (default)

One finger → passes through to the child (scroll normally). Two fingers → move candle + pinch pool. Long-press-then-drag → pick the candle up with a single finger. Tap → relight. The right fit when your child is a ListView / PageView / PDF viewer that must keep its own drag handling — which is most reader content.

Heads up: to pinch, place both fingers down together. Flutter's gesture arena hands the first finger to the scroll view the moment it passes touch-slop, so adding a second finger after you've started scrolling won't be recognised as a pinch. Lift, then touch with two fingers.

CandleLightInteraction.grab

All gestures drive the candle; child gets nothing. Single-finger drag moves the flame, pinch resizes, pinch hard blows it out, tap relights. Use for single-page readers or any content that doesn't need to scroll.

CandleLightInteraction.controlled

Widget consumes no gestures. Drive everything via CandleLightController. Use for custom input (keyboard, trackpad, eye-tracking, TTS sync, etc.).

Example app

A full paged-book reader is in example/. Run:

cd example
flutter run

License

MIT. See LICENSE.