linear_date_selector 🔗

A lightweight, customizable horizontal/vertical date selector widget for Flutter.

linear_date_selector provides a simple, robust UI for displaying a linear sequence of dates (e.g., today + next N days) with built-in selection, disabled-date support, animations, and a fully custom tile builder—similar to ListView.builder.

Link

Screenshots

| Default (Horizontal) | Default (Vertical) | Custom Tiles (Horizontal) |

✨ Features

Auto-generated date list starting from a provided todaysDateTime
Horizontal or vertical scrolling
Default, polished tile UI out of the box
Fully customizable tiles with LinearDateSelector.builder(...)
Disable specific dates (non-selectable)
Optional icon with flexible alignment: top, bottom, left, right
Tap scale (click) animation
Optional background and text color animations
Customizable animation durations
Simple API and small footprint — no heavy calendar widgets

🚀 Getting started

Add to your pubspec.yaml after publishing:

dependencies:
  linear_date_selector: ^0.0.1

Then run:

flutter pub get

Usage

Important: this package's constructors use startDateTime (item index 0 == startDateTime).

Default tiles (quick start)

import 'package:flutter/material.dart';
import 'package:linear_date_selector/linear_date_selector.dart';

// inside a widget build
LinearDateSelector(
  startDateTime: DateTime.now(),
  itemCount: 7,
  onDateTimeSelected: (selected) {
    print('selected: $selected');
  },
  // optional: an icon shown inside each tile
  icon: Icon(Icons.event),
  iconAlignment: LinearDateSelectorIconAlignment.bottom,
  // optional sizing
  itemWidth: 72,
  itemHeight: 80,
);

🧪 Custom builder (full control)

Use .builder to get (context, date, isSelected, isDisabled, index, style) and return any widget:

LinearDateSelector.builder(
  listPadding: const EdgeInsets.all(8),
  startDateTime: DateTime.now(),
  itemCount: 10,
  itemHeight: 120,
  axis: Axis.horizontal,
  disabledDateTimes: [
    DateTime.now().add(const Duration(days: 4)),
  ],
  onDateTimeSelected: (d) => print('selected $d'),
  itemBuilder: (
    context,
    date,
    isSelected,
    isDisabled,
    index,
    _,
  ) {
    return AnimatedContainer(
      duration: const Duration(milliseconds: 200),
      margin: const EdgeInsets.symmetric(horizontal: 6, vertical: 8),
      decoration: BoxDecoration(
        color: isDisabled
            ? Colors.grey.shade200
            : (isSelected ? const Color(0xFF1e1405) : const Color(0xFFf8e9d7)),
        borderRadius: BorderRadius.circular(10),
        border: Border.all(
          color: isDisabled
              ? Colors.grey
              : (isSelected ? const Color(0xFF1e1405) : const Color(0xFFf8e9d7)),
        ),
      ),
      child: Column(
        children: [
          Center(
            child: Text.rich(
              TextSpan(
                children: [
                  TextSpan(
                    text: '${DateFormat('dd').format(date)}\n',
                    style: const TextStyle(fontSize: 28),
                  ),
                  TextSpan(
                    text: DateFormat('MMM\nyyyy').format(date),
                    style: const TextStyle(fontSize: 14),
                  ),
                ],
              ),
              textAlign: TextAlign.center,
              style: TextStyle(
                color: isDisabled
                    ? Colors.grey
                    : (isSelected
                        ? const Color(0xFFf8e9d7)
                        : const Color(0xFF1e1405)),
                fontWeight: isSelected ? FontWeight.bold : FontWeight.normal,
              ),
            ),
          ),
        ],
      ),
    );
  },
);

Note: The index parameter corresponds to the tile's position (0 is todaysDateTime). Use it for special styling (e.g., first/last tile) or animations.

📅 Date-range (default tiles)


LinearDateSelector.dateRange(
  startDateTime: DateTime(2025, 1, 1),
  endDateTime: DateTime(2025, 1, 7), // inclusive → 1,2,3,4,5,6,7

  onDateTimeSelected: (selected) {
    print('selected: $selected');
  },

  // optional extras
  icon: const Icon(Icons.event),
  iconAlignment: LinearDateSelectorIconAlignment.top,
  itemWidth: 70,
  itemHeight: 85,
  enableColorAnimation: true,
  listPadding: const EdgeInsets.symmetric(horizontal: 12),
);

🎨 🧪 Date-range + custom builder (full control)

LinearDateSelector.dateRangeBuilder(
  startDateTime: DateTime(2025, 2, 10),
  endDateTime: DateTime(2025, 2, 15), // inclusive (6 days)

  disabledDateTimes: [
    DateTime(2025, 2, 12), // middle day disabled
  ],

  onDateTimeSelected: (selected) {
    print('picked: $selected');
  },

  listPadding: const EdgeInsets.all(10),
  axis: Axis.horizontal,
  itemWidth: 90,
  itemHeight: 120,

  itemBuilder: (
    context,
    date,
    isSelected,
    isDisabled,
    index,
    style,
  ) {
    final day = DateFormat('dd').format(date);
    final month = DateFormat('MMM').format(date);

    return AnimatedContainer(
      duration: const Duration(milliseconds: 250),
      margin: const EdgeInsets.symmetric(horizontal: 6),
      padding: const EdgeInsets.all(12),
      decoration: BoxDecoration(
        color: isDisabled
            ? Colors.grey.shade300
            : (isSelected ? Colors.blue : Colors.white),
        borderRadius: BorderRadius.circular(12),
        border: Border.all(
          color: isSelected ? Colors.blue : Colors.grey.shade400,
          width: 2,
        ),
      ),
      child: Column(
        mainAxisAlignment: MainAxisAlignment.center,
        children: [
          Text(
            day,
            style: TextStyle(
              fontSize: 28,
              fontWeight: FontWeight.bold,
              color: isDisabled ? Colors.grey : Colors.black,
            ),
          ),
          Text(
            month,
            style: TextStyle(
              fontSize: 16,
              color: isDisabled ? Colors.grey : Colors.black87,
            ),
          ),
        ],
      ),
    );
  },
);

📌 When to use:

You want different UI for weekdays vs weekends
You want animations, badges, chips, colors, shadows
UI designers give you custom Figma layouts
You need total control but want range logic for free

Note: .dateRange and .dateRangeBuilder ignore hours and minutes in the given DateTimes. Only the calendar day is used:

DateTime(2025, 1, 1, 23:00)
→ treated as 2025-01-01

API