flutter_body_part_selector 1.3.0
flutter_body_part_selector: ^1.3.0 copied to clipboard
Interactive body selector for Flutter. Tap muscles on SVG body diagram or select programmatically with visual highlighting. Includes built-in assets.
Flutter Body Part Selector #
An interactive body selector package for Flutter that allows users to select muscles on a body diagram. Users can tap on muscles in the SVG body diagram or select them programmatically, with visual highlighting of selected muscles.
The front and back body diagrams ship with the package; no asset setup is needed.
https://github.com/user-attachments/assets/8ba0b47b-fa72-4055-bee8-26f50427437c
Features #
- 🎯 Interactive Muscle Selection: Tap on any muscle in the body diagram to select it
- 🎨 Visual Highlighting: Selected muscles are automatically highlighted with customizable colors
- 🔄 Front/Back Views: Toggle between front and back body views
- 📱 Programmatic Control: Select muscles programmatically using the controller
- 🎛️ Customizable: Customize highlight colors and disabled muscle colors
- 🚫 Disabled Muscles: Lock muscles (injured, premium, unavailable) so they render greyed out and can't be selected
- 🪝 Hooks: Long-press, tooltip, semantic-label and selection-animation callbacks
- 📦 Easy to Use: Simple API with minimal setup required - includes all required assets
- 🎨 Built-in Assets: Package includes mandatory SVG body diagrams (front and back views)
Installation #
Add this to your package's pubspec.yaml file:
dependencies:
flutter_body_part_selector: ^1.3.0
Then run:
flutter pub get
Usage #
Quick Start #
Use InteractiveBodySvg with BodyMapController:
import 'package:flutter/material.dart';
import 'package:flutter_body_part_selector/flutter_body_part_selector.dart';
class BodySelectorExample extends StatefulWidget {
@override
State<BodySelectorExample> createState() => _BodySelectorExampleState();
}
class _BodySelectorExampleState extends State<BodySelectorExample> {
final controller = BodyMapController();
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: const Text('Interactive Body Selector'),
actions: [
IconButton(
icon: const Icon(Icons.flip),
onPressed: controller.toggleView,
tooltip: 'Flip view',
),
],
),
body: AnimatedBuilder(
animation: controller,
builder: (context, _) {
return Column(
children: [
if (controller.selectedMuscles.isNotEmpty)
Container(
padding: const EdgeInsets.all(16),
color: Colors.blue.shade900,
width: double.infinity,
child: Text(
'Selected: ${controller.selectedMuscles.length} muscles',
style: const TextStyle(color: Colors.white),
textAlign: TextAlign.center,
),
),
Expanded(
child: InteractiveBodySvg(
isFront: controller.isFront,
selectedMuscles: controller.selectedMuscles,
onMuscleTap: controller.toggleMuscle,
),
),
],
);
},
),
);
}
}
Using the Controller #
The BodyMapController manages the state of the body selector:
Basic Usage
final controller = BodyMapController();
// Select a muscle programmatically (toggles if already selected)
controller.toggleMuscle(Muscle.bicepsLeft);
// Clear all selections
controller.clearSelection();
// Toggle between front and back view
controller.toggleView();
// Set specific view
controller.setFrontView();
controller.setBackView();
// Access current state
final selected = controller.selectedMuscles; // Returns Set<Muscle> (read-only getter)
final isFront = controller.isFront; // Writable: setting it notifies listeners
// Set entire selection using setter (convenience)
controller.selectedMuscles = {Muscle.bicepsLeft, Muscle.tricepsRight};
Initialization with Pre-selected Muscles
// Create controller with initial selection
final controller = BodyMapController(
initialSelectedMuscles: {Muscle.bicepsLeft, Muscle.tricepsRight},
initialDisabledMuscles: {Muscle.chestLeft}, // Optional: pre-disable muscles
initialIsFront: true, // Optional: start with back view
);
Programmatic Selection Management
final controller = BodyMapController();
// Toggle a muscle's selection state
controller.toggleMuscle(Muscle.bicepsLeft);
// Deselect a specific muscle
controller.deselectMuscle(Muscle.bicepsLeft);
// Set entire selection (replaces current selection)
controller.setSelectedMuscles({
Muscle.bicepsLeft,
Muscle.tricepsRight,
Muscle.chestLeft,
});
// Add multiple muscles to current selection (without clearing)
controller.selectMultiple({
Muscle.bicepsLeft,
Muscle.tricepsRight,
});
// Check if a muscle is selected
if (controller.isSelected(Muscle.bicepsLeft)) {
print('Biceps left is selected');
}
// Get all selected muscles (read-only Set)
final selected = controller.selectedMuscles;
print('Selected ${selected.length} muscles');
Managing Disabled Muscles
final controller = BodyMapController();
// Disable a muscle (locks it, removes from selection)
controller.disableMuscle(Muscle.chestLeft);
// Enable a muscle (unlocks it)
controller.enableMuscle(Muscle.chestLeft);
// Set multiple disabled muscles at once
controller.setDisabledMuscles({
Muscle.chestLeft,
Muscle.chestRight,
});
// Check if a muscle is disabled
if (controller.isDisabled(Muscle.chestLeft)) {
print('Chest left is disabled');
}
Complete Example: Programmatic Selection Management
import 'package:flutter/material.dart';
import 'package:flutter_body_part_selector/flutter_body_part_selector.dart';
class BodySelectorPage extends StatefulWidget {
@override
State<BodySelectorPage> createState() => _BodySelectorPageState();
}
class _BodySelectorPageState extends State<BodySelectorPage> {
late BodyMapController controller;
@override
void initState() {
super.initState();
// Initialize with some pre-selected muscles
controller = BodyMapController(
initialSelectedMuscles: {Muscle.bicepsLeft, Muscle.tricepsRight},
);
}
@override
void dispose() {
controller.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Body Selector')),
body: Column(
children: [
// Control buttons
Padding(
padding: const EdgeInsets.all(16.0),
child: Wrap(
spacing: 8.0,
children: [
ElevatedButton(
onPressed: () {
// Select multiple muscles programmatically
controller.selectMultiple({
Muscle.bicepsLeft,
Muscle.bicepsRight,
});
},
child: const Text('Select Both Biceps'),
),
ElevatedButton(
onPressed: () {
// Set entire selection
controller.setSelectedMuscles({
Muscle.chestLeft,
Muscle.chestRight,
});
},
child: const Text('Select Chest Only'),
),
ElevatedButton(
onPressed: () {
// Clear all selections
controller.clearSelection();
},
child: const Text('Clear All'),
),
],
),
),
// Display selected muscles
AnimatedBuilder(
animation: controller,
builder: (context, _) {
return Container(
padding: const EdgeInsets.all(16),
color: Colors.blue.shade900,
width: double.infinity,
child: Text(
'Selected: ${controller.selectedMuscles.length} muscles',
style: const TextStyle(color: Colors.white),
textAlign: TextAlign.center,
),
);
},
),
// Body diagram
Expanded(
child: AnimatedBuilder(
animation: controller,
builder: (context, _) {
return InteractiveBodySvg(
isFront: controller.isFront,
selectedMuscles: controller.selectedMuscles,
onMuscleTap: controller.toggleMuscle,
);
},
),
),
],
),
);
}
}
Customization Options #
Colors and Styling
InteractiveBodySvg(
isFront: true, // Automatically uses package's front body asset
selectedMuscles: controller.selectedMuscles,
onMuscleTap: controller.toggleMuscle,
highlightColor: Colors.red.withValues(alpha: 0.7), // Custom highlight color
disabledColor: Colors.grey, // Custom color for disabled muscles
selectedStrokeWidth: 3.0, // Stroke width for selected muscles
unselectedStrokeWidth: 1.0, // Stroke width for unselected muscles
)
Color alpha is respected: a highlight color with alpha: 0.7 is drawn 70% opaque. Disabled muscles are additionally drawn at 40% opacity.
Size and Layout
InteractiveBodySvg(
isFront: true, // Automatically uses package's front body asset
selectedMuscles: controller.selectedMuscles,
onMuscleTap: controller.toggleMuscle,
width: 300, // Fixed width
height: 600, // Fixed height
fit: BoxFit.cover, // How to fit the SVG
alignment: Alignment.center, // Alignment within the widget
)
Selection Behavior
InteractiveBodySvg(
isFront: true, // Automatically uses package's front body asset
selectedMuscles: controller.selectedMuscles,
onMuscleTap: controller.toggleMuscle,
enableSelection: true, // Enable/disable tap selection
hitTestPadding: 2.0, // Padding for hit-testing (makes taps more forgiving)
onMuscleTapDisabled: (muscle) {
// Called when a disabled muscle is tapped, or any muscle while
// enableSelection is false
print('Tapped $muscle but it cannot be selected');
},
)
Taps fire when the finger lifts, so a scroll or drag that starts on a muscle does not select it, and a long press does not also count as a tap.
Hooks
InteractiveBodySvg(
selectedMuscles: controller.selectedMuscles,
onMuscleTap: controller.toggleMuscle,
// Long press on a muscle
onMuscleLongPress: (muscle) => print('Long-pressed ${muscle.displayName}'),
// Text shown in a SnackBar on long press (needs a ScaffoldMessenger,
// which MaterialApp provides). Return null to show nothing.
tooltipBuilder: (muscle) => '${muscle.displayName} - tap to select',
// Screen-reader label: the labels of the selected muscles, joined by commas
semanticLabelBuilder: (muscle) => '${muscle.displayName} selected',
// Wraps the diagram each time a muscle is newly selected. The subtree is
// rebuilt on every new selection, so this pulse replays each time.
onSelectAnimationBuilder: (context, child, muscle) {
return TweenAnimationBuilder<double>(
tween: Tween(begin: 1.04, end: 1.0),
duration: const Duration(milliseconds: 250),
builder: (context, scale, child) =>
Transform.scale(scale: scale, child: child),
child: child,
);
},
)
Available Muscles #
The package supports the following muscles:
Front View #
- Traps (Left/Right)
- Delts (Left/Right)
- Chest (Left/Right)
- Abs
- Biceps (Left/Right)
- Forearms (Left/Right)
- Quads (Left/Right)
- Calves (Left/Right)
Back View #
- Traps (Left/Right)
- Delts (Left/Right)
- Triceps (Left/Right)
- Lats (Left/Right)
- Lower Lats Back (Left/Right)
- Forearms (Left/Right)
- Glutes (Left/Right)
- Hamstrings (Left/Right)
- Calves (Left/Right)
Muscles that appear in both views (traps, delts, forearms, calves) map to the same Muscle value, so a selection made on one side stays highlighted on the other.
Assets #
The package includes the front and back SVG body diagrams, pre-configured with the muscle IDs the widget maps to Muscle values.
Using Package Assets #
The package includes default SVG assets that are automatically used. Simply use the isFront parameter:
InteractiveBodySvg(
isFront: true, // Automatically uses package's front body asset
selectedMuscles: controller.selectedMuscles,
onMuscleTap: controller.toggleMuscle,
)
Note: The package assets are automatically included when you add this package to your pubspec.yaml. No additional asset configuration is required in your app's pubspec.yaml.
API Reference #
InteractiveBodySvg #
The core widget for displaying the interactive body diagram.
Properties:
isFront(bool, default: true): Whether to show front view. Automatically uses the correct package asset based on this parameter.selectedMuscles(SetdisabledMuscles(SetonMuscleTap(void Function(Muscle)?, optional): Callback when a muscle is tappedhighlightColor(Color?, optional): Color for highlighting selected muscles (default: Colors.blue with opacity)disabledColor(Color?, optional): Color for disabled muscles (default: Colors.grey)selectedStrokeWidth(double, default: 2.0): Stroke width for selected musclesunselectedStrokeWidth(double, default: 1.0): Stroke width for unselected musclesenableSelection(bool, default: true): Enable/disable tap selectionfit(BoxFit, default: BoxFit.contain): How to fit the SVGhitTestPadding(double, default: 2.0): How far outside a muscle's edge, in SVG units, a tap still counts as hitting itwidth(double?, optional): Fixed widthheight(double?, optional): Fixed heightalignment(Alignment, default: Alignment.center): Alignment of SVGonMuscleTapDisabled(void Function(Muscle)?, optional): Callback when muscle is tapped but selection is disabledonMuscleLongPress(void Function(Muscle)?, optional): Callback when a muscle is long-pressedtooltipBuilder(String? Function(Muscle)?, optional): Text shown in a SnackBar when a muscle is long-pressedsemanticLabelBuilder(String? Function(Muscle)?, optional): Screen-reader label for each selected muscleonSelectAnimationBuilder(Widget Function(BuildContext, Widget, Muscle)?, optional): Wraps the diagram each time a muscle is newly selected; see HookshitTestBehavior(HitTestBehavior, default: deferToChild): Hit-test behavior of the gesture detectorloadingBuilder(WidgetBuilder?, optional): Widget shown while the SVG loads (default: a centeredCircularProgressIndicator). See Testing.asset(String?, optional, advanced): Overrides the built-in SVG path. Not recommended; see Common Pitfalls.isInitialSelection(bool, deprecated): Ignores taps whiletrue. No longer needed; pass the starting selection throughselectedMusclesinstead.
BodyMapController #
Controller for managing the body selector state.
Constructor:
BodyMapController({Set<Muscle>? initialSelectedMuscles, Set<Muscle>? initialDisabledMuscles, bool initialIsFront = true}): Create a controller with optional initial state
Selection Methods (Writable):
toggleMuscle(Muscle): Select the muscle, or deselect it if already selected. Pass it asonMuscleTapfor tap-to-toggleselectMuscle(Muscle): Same astoggleMuscle(it also deselects an already-selected muscle); kept for compatibilitydeselectMuscle(Muscle): Deselect a specific musclesetSelectedMuscles(Set<Muscle>): Set the entire selection (replaces current selection)selectMultiple(Set<Muscle>): Add multiple muscles to current selection (without clearing)clearSelection(): Clear all selections
View Methods (Writable):
-
toggleView(): Toggle between front and back view -
setFrontView(): Set view to front -
setBackView(): Set view to back -
setInitialSelection(Set<Muscle>): Replace the selection without notifying listeners, for seeding state before the first build
Disabled Muscle Methods (Writable):
disableMuscle(Muscle): Disable a muscle (locks it, removes from selection)enableMuscle(Muscle): Enable a muscle (unlocks it)setDisabledMuscles(Set<Muscle>): Set multiple disabled muscles at once
Properties:
selectedMuscles(SetdisabledMuscles(SetisFront(bool, writable): Whether showing front view. Can be set directly (notifies listeners) or use view methods.isSelected(Muscle)(bool, read-only): Check if a muscle is selectedisDisabled(Muscle)(bool, read-only): Check if a muscle is disabled
Muscle #
Enum representing all available muscles. See the "Available Muscles" section above for the complete list.
Common Pitfalls #
❌ Don't: Try to modify selectedMuscles Set directly #
// ❌ WRONG - This won't work because the Set is unmodifiable
controller.selectedMuscles.add(Muscle.bicepsLeft); // Error!
controller.selectedMuscles.clear(); // Error!
✅ Do: Use the setter or provided methods #
// ✅ CORRECT - Use the setter (replaces entire selection)
controller.selectedMuscles = {Muscle.bicepsLeft, Muscle.tricepsRight};
// ✅ CORRECT - Or use the controller methods
controller.toggleMuscle(Muscle.bicepsLeft);
controller.setSelectedMuscles({Muscle.bicepsLeft, Muscle.tricepsRight});
controller.clearSelection();
❌ Don't: Forget to listen to controller changes #
// ❌ WRONG - UI won't update when selection changes
final controller = BodyMapController();
controller.toggleMuscle(Muscle.bicepsLeft);
// Widget won't rebuild automatically
✅ Do: Use AnimatedBuilder or listen to changes #
// ✅ CORRECT - Wrap with AnimatedBuilder
AnimatedBuilder(
animation: controller,
builder: (context, _) {
return Text('Selected: ${controller.selectedMuscles.length}');
},
)
❌ Don't: Create controller in build method #
// ❌ WRONG - Creates new controller on every rebuild
Widget build(BuildContext context) {
final controller = BodyMapController(); // Don't do this!
return InteractiveBodySvg(...);
}
✅ Do: Create controller in initState or use late initialization #
// ✅ CORRECT - Create once in initState
class _MyWidgetState extends State<MyWidget> {
late BodyMapController controller;
@override
void initState() {
super.initState();
controller = BodyMapController();
}
@override
void dispose() {
controller.dispose();
super.dispose();
}
}
❌ Don't: Forget to dispose the controller #
// ❌ WRONG - Memory leak!
class _MyWidgetState extends State<MyWidget> {
final controller = BodyMapController();
// Missing dispose() call
}
✅ Do: Always dispose controllers #
// ✅ CORRECT - Always dispose
@override
void dispose() {
controller.dispose();
super.dispose();
}
❌ Don't: Use a custom SVG without the package's element IDs #
// ❌ WRONG - Muscle taps and highlights only work for elements whose
// IDs match the package's built-in SVGs (e.g. `biceps_left`, `lats_right`)
InteractiveBodySvg(
asset: 'assets/my_body.svg',
)
The asset parameter is an advanced override. Each muscle must be a <path> or a <g> of paths whose id matches the built-in SVGs. If the asset can't be loaded, the widget shows an error instead of falling back to the built-in diagram.
✅ Do: Use the package's included assets #
// ✅ CORRECT - Automatically uses package assets
InteractiveBodySvg(
isFront: true, // Automatically uses package's front body asset
)
Testing #
InteractiveBodySvg loads its SVG asynchronously from the asset bundle. Under the flutter_test fake clock that load does not complete on its own, and the default loading spinner animates forever, so tester.pumpAndSettle() times out.
If your test doesn't need the diagram itself (you're testing surrounding UI), pass a static loadingBuilder and pumpAndSettle() works normally:
await tester.pumpWidget(MaterialApp(
home: Scaffold(
body: InteractiveBodySvg(
loadingBuilder: (context) => const SizedBox.shrink(),
),
),
));
await tester.pumpAndSettle(); // settles; the SVG stays unloaded
If your test needs the rendered diagram, let the real asset I/O run inside tester.runAsync:
await tester.runAsync(() async {
await tester.pumpWidget(MaterialApp(home: Scaffold(body: InteractiveBodySvg())));
// The first parse can take over a second; poll until the SVG appears.
for (var i = 0; i < 100 && find.byType(SvgPicture).evaluate().isEmpty; i++) {
await Future<void>.delayed(const Duration(milliseconds: 50));
await tester.pump();
}
});
await tester.pump();
expect(find.byType(SvgPicture), findsOneWidget); // from package:flutter_svg
Contributing #
Contributions are welcome! Please feel free to submit a Pull Request.
License #
This project is licensed under the MIT License.
Support #
If you encounter any issues or have questions, please file an issue on the GitHub repository.