apptomate_custom_switch 0.0.2

A highly customizable animated toggle switch with label support and smooth transitions.

CustomSwitch

A highly customizable animated toggle switch with label support and smooth transitions.

Features

• Enhanced Label Support:

  • Text or custom widget labels
  • Flexible left/right positioning
  • Automatic spacing

• Smooth Animations:

  • Physics-based toggle movement
  • 200ms optimized duration
  • Alignment-based transition

• Visual Customization:

  • Dual-state color customization
  • Adjustable sizing parameters
  • Configurable border radius
  • Custom border styling for each state

Installation

Add the dependency to your pubspec.yaml:

dependencies:
  apptomate_custom_switch: ^0.0.2

Basic Usage

bool isActive = false;

// Minimal implementation
CustomSwitch(
  value: isActive,
  onToggle: (value) => setState(() => isActive = value),
)

// With text label
CustomSwitch(
  value: isActive,
  onToggle: (value) => setState(() => isActive = value),
  label: "Enable Feature",
)

// With custom label widget
CustomSwitch(
  value: isActive,
  onToggle: (value) => setState(() => isActive = value),
  labelWidget: Row(
    children: [
      Icon(Icons.power_settings_new),
      Text("Power Mode"),
    ],
  ),
  labelPosition: LabelPosition.left,
)

Complete Example

class SwitchExample extends StatefulWidget {
  @override
  _SwitchExampleState createState() => _SwitchExampleState();
}

class _SwitchExampleState extends State<SwitchExample> {
  bool _darkMode = false;
  bool _notifications = true;

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        CustomSwitch(
          value: _darkMode,
          onToggle: (val) => setState(() => _darkMode = val),
          label: "Dark Mode",
          activeColor: Colors.black45,
          inactiveColor: Colors.grey[200]!,
          activeToggleColor: Colors.black,
          inactiveToggleColor: Colors.white,
          width: 50,
          height: 30,
        ),
        
        const SizedBox(height: 20),
        
        CustomSwitch(
          value: _notifications,
          onToggle: (val) => setState(() => _notifications = val),
          labelWidget: Row(
            children: [
              Icon(Icons.notifications, size: 18),
              const SizedBox(width: 4),
              const Text("Notifications"),
            ],
          ),
          labelPosition: LabelPosition.left,
          activeColor: Colors.blue[100]!,
          activeToggleColor: Colors.blue,
        ),
      ],
    );
  }
}

Parameter Reference

Core Properties

Parameter	Type	Required	Description
value	bool	Yes	Current switch state
onToggle	ValueChanged<bool>	Yes	State change callback

Label Options

Parameter	Type	Default	Description
label	String?	null	Text label
labelWidget	Widget?	null	Custom label widget
labelPosition	LabelPosition	right	Label position

Color Customization

Parameter	Type	Default	Description
activeColor	Color	Colors.grey	Active background
inactiveColor	Color	Colors.grey	Inactive background
activeToggleColor	Color	Colors.blue	Active toggle color
inactiveToggleColor	Color	Colors.white	Inactive toggle color

Size Customization

Parameter	Type	Default	Description
width	double	30.0	Switch width
height	double	21.3	Switch height
toggleSize	double	11.0	Toggle circle size
borderRadius	double	30.0	Container border radius
padding	double	3.0	Inner padding

Border Customization

Parameter	Type	Default	Description
activeBorder	Border?	null	Active state border
inactiveBorder	Border?	null	Inactive state border

Advanced Usage

Custom Border Example

CustomSwitch(
  value: _isPremium,
  onToggle: (val) => setState(() => _isPremium = val),
  activeBorder: Border.all(color: Colors.amber, width: 1.5),
  inactiveBorder: Border.all(color: Colors.grey, width: 1),
)

Label Positioning

Row(
  children: [
    CustomSwitch(
      value: _leftAligned,
      onToggle: (val) => setState(() => _leftAligned = val),
      label: "Left Label",
      labelPosition: LabelPosition.left,
    ),
    Spacer(),
    CustomSwitch(
      value: _rightAligned,
      onToggle: (val) => setState(() => _rightAligned = val),
      label: "Right Label",
    ),
  ],
)

Complex Label Widget

CustomSwitch(
  value: _advanced,
  onToggle: (val) => setState(() => _advanced = val),
  labelWidget: Column(
    crossAxisAlignment: CrossAxisAlignment.start,
    children: [
      Text("Advanced Mode", style: TextStyle(fontWeight: FontWeight.bold)),
      Text("Enable experimental features", 
           style: TextStyle(fontSize: 12, color: Colors.grey)),
    ],
  ),
)

Best Practices

1. Size Proportions:

   • Maintain toggleSize < height - (padding * 2)
   • Recommended width/height ratio ≈ 1.4:1

2. Color Contrast:

   • Ensure toggle is visible against background
   • Follow WCAG contrast guidelines

3. Label Clarity:

   • Use short, descriptive labels
   • Consider icons for quick recognition

4. State Management:

   • Connect to app state when needed
   • Consider debouncing for rapid toggles

Troubleshooting

Toggle not animating:

• Verify onToggle updates the state
• Check animation controller initialization

Label not appearing:

• Ensure either label or labelWidget is provided
• Verify there's space in the layout

Visual glitches:

• Check size proportions
• Ensure border radius <= height/2