Neon Timeline Flutter #

A highly adaptive, responsive timeline and day planner platform for Flutter. It features stable coordinate-correct drag-and-drop, snapping grid, overlap handling, continuous zoom, frame diagnostics, and legacy migration APIs.

Visual Showcase Gallery #

Every generation is preserved in the example app. All image links below use package-relative paths, so the complete gallery is also rendered on pub.dev.

v16 Compact Mobile	v15 Ultra Planner	v14 Friendly UI

v13 Workspace Shell	v12 Neon Design System	v11 Accessible History

v10 Delight Snapping	v9 Zoom & Virtualization	v8 Drag & Resize

v7 Structured UI	v6 Planning Engine	v5 Command Center

V4 Enterprise Views #

Agenda	Day	Planner

Resources	Roadmap	Studio

V5 Productivity Views #

Board	Focus	Matrix	Scenarios

Theme Gallery #

Aurora	Cryogenic	Ember	Hologram

Hyperion	Light	Midnight	Neon

Neural Aurora	Neural Ember	Omniverse

Seeded	Solar Flare	Spectral

Installation & Requirements #

System Requirements #

Dart SDK: >=3.12.0 <4.0.0
Flutter SDK: >=3.44.0
Dependencies: flutter_slidable: '>=3.1.2 <4.0.0'

Add to Project #

Run this command in your package root:

flutter pub add neon_timeline_flutter

Or reference a local path dependency in pubspec.yaml:

dependencies:
  neon_timeline_flutter:
    path: /path/to/neon_timeline_flutter

Imports #

Import the modern V16 unified namespace:

import 'package:neon_timeline_flutter/timeline_v16.dart';

Or keep imports focused on specific library layers:

import 'package:neon_timeline_flutter/timeline_core.dart';
import 'package:neon_timeline_flutter/timeline_views.dart';
import 'package:neon_timeline_flutter/timeline_themes.dart';

Quick Start (V16 Compact Planner) #

Initialize the timeline by projecting your local task models onto the timeline engine.

1. Define Your Model #

class Task {
  final String id;
  final String title;
  final String? note;
  final DateTime start;
  final Duration duration;
  final IconData icon;
  final NeonPlannerEntryKind kind;

  Task({
    required this.id,
    required this.title,
    this.note,
    required this.start,
    required this.duration,
    required this.icon,
    required this.kind,
  });

  Task copyWith({DateTime? start, Duration? duration}) {
    return Task(
      id: id,
      title: title,
      note: note,
      start: start ?? this.start,
      duration: duration ?? this.duration,
      icon: icon,
      kind: kind,
    );
  }
}

2. Implement the Widget #

class PlannerPage extends StatefulWidget {
  const PlannerPage({super.key});

  @override
  State<PlannerPage> createState() => _PlannerPageState();
}

class _PlannerPageState extends State<PlannerPage> {
  final _day = DateTime(2026, 7, 19);

  List<Task> _tasks = [
    Task(
      id: 'sleep',
      title: 'Nachtschlaf',
      note: 'Erholungsphase',
      start: DateTime(2026, 7, 19, 0, 0),
      duration: const Duration(hours: 7, minutes: 30),
      icon: Icons.brightness_3_rounded,
      kind: NeonPlannerEntryKind.sleep,
    ),
    Task(
      id: 'focus',
      title: 'Konzentriertes Arbeiten',
      note: 'Wichtigstes Projekt zuerst',
      start: DateTime(2026, 7, 19, 8, 30),
      duration: const Duration(minutes: 50),
      icon: Icons.center_focus_strong_rounded,
      kind: NeonPlannerEntryKind.focus,
    ),
  ];

  @override
  Widget build(BuildContext context) {
    // 1. Define the adapter to project models into presentation
    final adapter = NeonPlannerEntryAdapter<Task>(
      id: (task) => task.id,
      start: (task) => task.start,
      duration: (task) => task.duration,
      presentation: (task) => NeonPlannerEntryPresentation(
        title: task.title,
        subtitle: task.note,
        icon: task.icon,
        kind: task.kind,
      ),
    );

    // 2. Render the timeline widget
    return Scaffold(
      body: SafeArea(
        child: NeonPlannerDayTimeline<Task>(
          entries: _tasks,
          adapter: adapter,
          selectedDate: _day,
          fit: NeonPlannerDayFit.scroll,
          autoResponsiveDensity: true,
          dragMode: NeonPlannerDayDragMode.time,
          snapInterval: const Duration(minutes: 5),
          enableResize: true,
          onEntryMove: (proposal) {
            setState(() {
              _tasks = _tasks.map((t) => t.id == proposal.entry.data.id
                  ? t.copyWith(start: proposal.proposedStart)
                  : t).toList();
            });
            return const NeonPlannerMutationResult.accepted('Erfolgreich verschoben.');
          },
          onEntryResize: (proposal) {
            setState(() {
              _tasks = _tasks.map((t) => t.id == proposal.entry.data.id
                  ? t.copyWith(
                      start: proposal.proposedStart,
                      duration: proposal.proposedEnd.difference(proposal.proposedStart),
                    )
                  : t).toList();
            });
            return const NeonPlannerMutationResult.accepted('Zeitdauer angepasst.');
          },
        ),
      ),
    );
  }
}

V16 Mapping with Entry Adapters #

NeonPlannerEntryAdapter<T> adapts any data type T to the timeline presentation model without modifying your domain model.

NeonPlannerEntryAdapter<T>(
  id: (T item) => Object,        // Unique ID for delta updates
  start: (T item) => DateTime,   // Entry start boundary
  duration: (T item) => Duration,// Entry temporal length
  presentation: (T item) => NeonPlannerEntryPresentation, // Styling mapping
)

Presentation Configs (`NeonPlannerEntryPresentation`) #

title: Primary header label.
subtitle: Supporting info (displayed when height is sufficient).
metadata: High-density details line.
icon: Displayed inside the circular hub timeline markers.
kind: Maps to standard category colors and default badges (Sleep, Travel, Focus, Break, etc.).
accentColor: Explicit color override bypassing category theme palettes.
completion: Fractional value (0.0 - 1.0) rendering a progress ring around the entry node.

V16 API Parameter Reference #

`NeonPlannerDayTimeline<T>` #

Parameter	Type	Default	Description
`entries`	`List<T>`	Required	List of domain model items to project.
`adapter`	`NeonPlannerEntryAdapter<T>`	Required	Projector converting `T` into UI presentations.
`selectedDate`	`DateTime`	Required	Bounding date for the schedule.
`fit`	`NeonPlannerDayFit`	`smart`	Fits layout to `content`, `scroll` internally, or selects automatically (`smart`).
`density`	`double`	`1.0`	Vertical density scaler for timeline rows.
`autoResponsiveDensity`	`bool`	`false`	Automatically scales rows based on screen width.
`dragMode`	`NeonPlannerDayDragMode`	`disabled`	Allows pointer drag: `disabled`, `time` scaling, or `slot` suggestions.
`enableResize`	`bool`	`false`	Enables start/end bounds handle dragging.
`snapInterval`	`Duration`	`Duration(minutes: 5)`	Intervals to clamp start/end boundaries on drag.
`conflictPolicy`	`NeonPlannerConflictPolicy`	`allow`	Overlap behavior: `allow`, `block`, or `delegate`.
`showGrabber`	`bool`	`true`	Renders a sheet drawer notch at the container top.
`showHeader`	`bool`	`true`	Renders the timeline navigation header.
`showMetrics`	`bool`	`true`	Renders KPI summaries (Tasks count, focus hours, sleep tracker).
`borderRadius`	`double`	`42.0`	Outer card boundary border radius. Set to `0` for flat layouts.
`backgroundColor`	`Color?`	`null`	Widget base container color (defaults to theme surface).
`theme`	`NeonPlannerTimelineThemeData?`	`null`	Timeline visual styling values and override colors.

`NeonPlannerTimelineConfig` (Advanced Planner Configurations) #

zoomLevel: Standardized scale preset (e.g. balanced, comfortable).
snapStrength: Magnetic pull radius towards adjacent entries (soft, balanced, strong).
showTimeScrubber: Displays duration feedback tags while resizing.
enableHaptics: Fires subtle vibration ticks on snap transitions.

Snapping & Drag-and-Drop Interaction #

The scheduling engine handles complex temporal mutations out-of-the-box.

       [Drag Handle] -> Lift entry
            |
            v
       [Magnetic Snap] -> Pulls boundaries to adjacent gaps/slots
            |
            v
   [Conflict Checking] -> Evaluates overlap policy
            |
            v
     [onEntryMove()] -> Dispatches proposal back to host app

Mutation Callback Contracts #

onEntryMove: Fired when dragging is finalized. Returns a NeonPlannerMutationResult.
onEntryResize: Fired when edge resizing completes. Returns a NeonPlannerMutationResult.

onEntryMove: (proposal) {
  if (proposal.hasConflict && _mustBlock) {
    return const NeonPlannerMutationResult.rejected('Kollision blockiert.');
  }
  // Persist model updates...
  return const NeonPlannerMutationResult.accepted('Änderung gespeichert.');
}

Theming & Color Customization #

Preset Themes #

The package exports visual styling configurations out-of-the-box:

NeonPlannerTimelineThemeData.light() - Balanced, clean professional theme.
NeonPlannerTimelineThemeData.dark() - Ambient, glow-accented dark mode.

Custom Styling Override #

To override colors, shadows, and fonts:

final customTheme = NeonPlannerTimelineThemeData.light().copyWith(
  accentColor: const Color(0xFF6C5CE7),
  surfaceColor: const Color(0xFFF9F9FB),
  gridColor: const Color(0xFFE2E8F0),
);

Borderless Flat Layout #

To integrate the planner seamlessly as a flat page widget (as shown in our Dashboard Showcase):

NeonPlannerDayTimeline<Task>(
  borderRadius: 0,
  showGrabber: false,
  showHeader: false,
  backgroundColor: Colors.transparent,
  theme: NeonPlannerTimelineTheme.of(context).copyWith(
    shadowColor: Theme.of(context).scaffoldBackgroundColor.withValues(alpha: 0),
  ),
  // ...
)

Responsive Breakpoints & Density #

The planner dynamically shifts details density depending on available width constraints:

Micro Layout (<360px): Drops text fields, merges timelines into single compact line, maps status indicator tags.
Compact Layout (360px - 480px): Renders compact labels and side-by-side gap metrics.
Regular Layout (>480px): Full-bleed double track, semantic timelines, expanded task descriptions, and persistent metrics.

Virtualization & Performance Policy #

Timelines manage dense data using an adaptive virtualization layer:

Lazy Rendering: Off-viewport entry cards are not instantiated, keeping list layout computations at a constant $O(N)$ with respect to screen size rather than task count.
Diagnostics Overlay: Set showDiagnostics: true inside NeonPlannerTimelineConfig to audit frame times, layout cache misses, and overlaps during runtime.

Legacy API Catalog (V15 - V10) #

All original timeline paradigms are preserved for backwards compatibility.

V15: Ultra Adaptive Planner #

Semantic continuous zoom and magnetic snapping:

AdaptivePlannerTimeline<T>(
  values: tasks,
  engine: engine,
  selectedDate: selectedDate,
  title: 'Ultra Planner v15',
  controller: ultraController,
  config: const UltraTimelineConfig.production(),
  onMove: moveTask,
  onResize: resizeTask,
)

V14: Friendly UI Structured Timeline #

Colorful, icon-led presentation with card abstraction:

FriendlyUiStructuredTimeline<T>(
  values: tasks,
  engine: engine,
  selectedDate: selectedDate,
  title: 'Friendly Planner',
  onMove: moveTask,
  entryPresentationBuilder: (context, details) =>
      FriendlyTimelineEntryPresentation(
        details: details,
        title: details.value.toString(),
        icon: Icons.calendar_month,
        tone: FriendlyTimelineIconTone.mint,
      ),
)

V13: Advanced Workspace Shell #

Fully responsive workspace with built-in KPI banners, navigation rail, and commands:

AdvancedUiStructuredTimeline<T>(
  values: tasks,
  engine: engine,
  selectedDate: selectedDate,
  title: 'Workspace Planner',
  metrics: const [
    AdvancedTimelineMetric(
      label: 'Completed',
      value: '3 / 5',
      icon: Icons.check_circle_rounded,
    )
  ],
  onMove: moveTask,
)

V12: Ultimate Structured Timeline #

Adaptive cards, auto-scroll bounds, and focus gaps:

UltimateStructuredTimeline<T>(
  values: tasks,
  engine: engine,
  selectedDate: selectedDate,
  config: const UltimateStructuredTimelineConfig.production(),
  onMove: moveTask,
)

V10: Delight Snapping Timeline #

Coordinate-correct pixel-to-time mapping engine:

DelightStructuredTimeline<T>(
  values: tasks,
  engine: engine,
  selectedDate: selectedDate,
  experience: const StructuredTimelineExperience.delight(),
  onMove: moveTask,
)

Created and maintained by rayanMS1122. Licensed under the MIT License.

neon_timeline_flutter 16.0.1 neon_timeline_flutter: ^16.0.1 copied to clipboard

Metadata