Now that you know how to manage state in your Flutter app, how can you let users interact with your app and change its state?

As a multi-platform UI framework, there are many different ways for users to interact with a Flutter app. The resources in this section introduce you to some of the common widgets used for enabling user interaction within your app.

Some user input mechanisms, likescrolling, have already been covered inLayouts.

menu_bookReference: Thewidget catalog has an inventory of commonly used widgets in theMaterial andCupertino libraries.

Next, we'll cover a few of the Material widgets that support common use cases for handling user input in your Flutter app.

Buttons allow a user to initiate an action in the UI by clicking or tapping. The Material library provides a variety of button types that are functionally similar, but styled differently for various use cases, including:

• ElevatedButton: A button with some depth. Use elevated buttons to add dimension to otherwise mostly flat layouts.
• FilledButton: A filled button that should be used for important, final actions that complete a flow, likeSave,Join now, orConfirm.
• Tonal Button: A middle ground button betweenFilledButton andOutlinedButton. They're useful in contexts where a lower-priority button requires more emphasis than an outline, likeNext.
• OutlinedButton: A button with text and a visible border. These buttons contain actions that are important, but aren't the primary action in an app.
• TextButton: Clickable text, without a border. Since text buttons don't have visible borders, they must rely on their position relative to other content for context.
• IconButton: A button with an icon.
• FloatingActionButton: An icon button that hovers over content to promote a primary action.

slideshowVideo:FloatingActionButton (Widget of the Week)

There are usually 3 main aspects to constructing a button: style, callback, and its child, as seen in the followingElevatedButton sample code:

• A button's callback function,onPressed, determines what happens when the button is clicked, therefore, this function is where you update your app state. If the callback isnull, the button is disabled and nothing happens when a user presses the button.

• The button'schild, which is displayed within the button's content area, is usually text or an icon that indicates the button's purpose.

• Finally, a button'sstyle controls its appearance: color, border, and so on.

dart

intcount=0;​@overrideWidgetbuild(BuildContextcontext){returnElevatedButton(style:ElevatedButton.styleFrom(textStyle:constTextStyle(fontSize:20),),onPressed:(){setState((){count+=1;});},child:constText('Enabled'),);}

content_copy

starCheckpoint: Complete this tutorial that teaches you how to build a "favorite" button:Add interactivity to your Flutter app

menu_bookAPI Docs:ElevatedButton •FilledButton •OutlinedButton •TextButton •IconButton •FloatingActionButton

Several widgets support text input.

Flutter'sText widget displays text on the screen, but doesn't allow users to highlight or copy the text.SelectableText displays a string ofuser-selectable text.

dart

@overrideWidgetbuild(BuildContextcontext){returnconstSelectableText('''Two households, both alike in dignity,In fair Verona, where we lay our scene,From ancient grudge break to new mutiny,Where civil blood makes civil hands unclean.From forth the fatal loins of these two foes''');}

content_copy

slideshowVideo:SelectableText (Widget of the Week)

RichText lets you display strings of rich text in your app.TextSpan, similar toRichText, allows you to display parts of text with different text styles. It's not for handling user input, but is useful if you're allowing users edit and format text.

dart

@overrideWidgetbuild(BuildContextcontext){returnRichText(text:TextSpan(text:'Hello',style:DefaultTextStyle.of(context).style,children:const<TextSpan>[TextSpan(text:'bold',style:TextStyle(fontWeight:FontWeight.bold)),TextSpan(text:' world!'),],),);}

content_copy

slideshowVideo:Rich Text (Widget of the Week)

codeCode:Rich Text Editor code

ATextField lets users enter text in text box using a hardware or onscreen keyboard.

TextFields have many different properties and configurations. A few of the highlights:

• InputDecoration determines the text field's appearance, such as color and border.
• controller: ATextEditingController controls the text being edited. Why might you need a controller? By default, your app's users can type into the text field, but if you want to programmatically control theTextField and clear its value, for example, you'll need aTextEditingController.
• onChanged: This callback function triggers when the user changes the text field's value, such as when inserting or removing text.
• onSubmitted: This callback is triggered when the user indicates that they are done editing the text in the field; for example, by tapping the "enter" key when the text field is in focus.

The class supports other configurable properties, such asobscureText that turns each letter into areadOnly circle as its entered andreadOnly which prevents the user from changing the text.

dart

finalTextEditingController_controller=TextEditingController();​@overrideWidgetbuild(BuildContextcontext){returnTextField(controller:_controller,decoration:constInputDecoration(border:OutlineInputBorder(),labelText:'Mascot Name',),);}

content_copy

starCheckpoint: Complete this 4-part cookbook series that walks you through how to create a text field, retrieve its value, and update your app state:

1. Create and style a text field
2. Retrieve the value of a text field
3. Handle changes to a text field
4. Focus and text fields.

Form is an optional container for grouping together multiple form field widgets, such asTextField.

Each individual form field should be wrapped in aFormField widget with theForm widget as a common ancestor. Convenience widgets exist that pre-wrap form field widgets in aFormField for you. For example, theForm widget version ofTextField isTextFormField.

Using aForm provides access to aFormState, which lets you save, reset, and validate eachFormField that descends from thisForm. You can also provide aGlobalKey to identify a specific form, as shown in the following code:

finalGlobalKey<FormState>_formKey=GlobalKey<FormState>();​@overrideWidgetbuild(BuildContextcontext){returnForm(key:_formKey,child:Column(crossAxisAlignment:CrossAxisAlignment.start,children:<Widget>[TextFormField(decoration:constInputDecoration(hintText:'Enter your email',),validator:(String?value){if(value==null||value.isEmpty){return'Please enter some text';}returnnull;},),Padding(padding:constEdgeInsets.symmetric(vertical:16.0),child:ElevatedButton(onPressed:(){// Validate returns true if the form is valid, or false otherwise.if(_formKey.currentState!.validate()){// Process data.}},child:constText('Submit'),),),],),);}

starCheckpoint: Complete this tutorial to learn how tobuild a form with validation.

flutterDemo:Form app

codeCode:Form app code

menu_bookAPI Docs:TextField •RichText •SelectableText •Form

Provide a way to users to select from several options.

SegmentedButton allows users to select from a minimal group of 2-5 items.

The data type,<T>, can be a built-in type such asint,String,bool or an enum. ASegmentedButton has a few relevant properties:

• segments, a list ofButtonSegments, where each represents a "segment" or option that the user can select. Visually, eachButtonSegment can have an icon, text label, or both.

• multiSelectionEnabled indicates whether the user is allowed to select multiple options. This property defaults to false.

• selected identifies the currently selected value(s).Note:selected is of type ofSet<T>, so if you're only allowing users to select one value, that value must be provided as aSet with a single element.

• TheonSelectionChanged callback triggers when a user selects any segments. It provides a list of the selected segments so you can update your app state.

• Additional styling parameters allow you to modify the button's appearance. For example,style takes aButtonStyle, providing a way to configure aselectedIcon.

dart

enumCalendar{day,week,month,year}​// StatefulWidget...CalendarcalendarView=Calendar.day;​@overrideWidgetbuild(BuildContextcontext){returnSegmentedButton<Calendar>(segments:const<ButtonSegment<Calendar>>[ButtonSegment<Calendar>(value:Calendar.day,label:Text('Day'),icon:Icon(Icons.calendar_view_day)),ButtonSegment<Calendar>(value:Calendar.week,label:Text('Week'),icon:Icon(Icons.calendar_view_week)),ButtonSegment<Calendar>(value:Calendar.month,label:Text('Month'),icon:Icon(Icons.calendar_view_month)),ButtonSegment<Calendar>(value:Calendar.year,label:Text('Year'),icon:Icon(Icons.calendar_today)),],selected:<Calendar>{calendarView},onSelectionChanged:(Set<Calendar>newSelection){setState((){// By default, there is only a single segment that can be// selected at a time, so its value is always the firstcalendarView=newSelection.first;});},);}

content_copy

Chip is a compact way of representing an attribute, text, entity, or action for a specific context. SpecializedChip widgets exist for specific use cases:

• InputChip represents a complex piece of information, such as an entity (person, place, or thing), or conversational text, in a compact form.
• ChoiceChip allows a single selection from a set of options. Choice chips contain related descriptive text or categories.
• FilterChip uses tags or descriptive words to filter content.
• ActionChip represents an action related to primary content.

EveryChip widget requires alabel. It can optionally have anavatar (such as an icon or a user's profile picture) and anonDeleted callback, which shows a delete icon that when triggered, deletes the chip. AChip widget's appearance can also be customized by setting a number of optional parameters such asshape,color, andiconTheme.

You will typically useWrap, a widget that displays its children in multiple horizontal or vertical runs, to make sure your chips wrap and don't get cut off at the edge of your app.

dart

@overrideWidgetbuild(BuildContextcontext){returnconstSizedBox(width:500,child:Wrap(alignment:WrapAlignment.center,spacing:8,runSpacing:4,children:[Chip(avatar:CircleAvatar(backgroundImage:AssetImage('assets/images/dash_chef.png')),label:Text('Chef Dash'),),Chip(avatar:CircleAvatar(backgroundImage:AssetImage('assets/images/dash_firefighter.png')),label:Text('Firefighter Dash'),),Chip(avatar:CircleAvatar(backgroundImage:AssetImage('assets/images/dash_musician.png')),label:Text('Musician Dash'),),Chip(avatar:CircleAvatar(backgroundImage:AssetImage('assets/images/dash_artist.png')),label:Text('Artist Dash'),),],),);}

content_copy

ADropdownMenu allows users to select a choice from a menu of options and places the selected text into aTextField. It also allows users to filter the menu items based on the text input.

Configuration parameters include the following:

• dropdownMenuEntries provides a list ofDropdownMenuEntrys that describes each menu item. The menu might contain information such as a text label, and a leading or trailing icon. (This is also the only required parameter.)
• TextEditingController allows programmatically controlling theTextField.
• TheonSelected callback triggers when the user selects an option.
• initialSelection allows you to configure the default value.
• Additional parameters are also available for customizing the widget's look and behavior.

dart

enumColorLabel{blue('Blue',Colors.blue),pink('Pink',Colors.pink),green('Green',Colors.green),orange('Orange',Colors.orange),grey('Grey',Colors.grey);​constColorLabel(this.label,this.color);finalStringlabel;finalColorcolor;}​// StatefulWidget...@overrideWidgetbuild(BuildContextcontext){returnDropdownMenu<ColorLabel>(initialSelection:ColorLabel.green,controller:colorController,// requestFocusOnTap is enabled/disabled by platforms when it is null.// On mobile platforms, this is false by default. Setting this to true will// trigger focus request on the text field and virtual keyboard will appear// afterward. On desktop platforms however, this defaults to true.requestFocusOnTap:true,label:constText('Color'),onSelected:(ColorLabel?color){setState((){selectedColor=color;});},dropdownMenuEntries:ColorLabel.values.map<DropdownMenuEntry<ColorLabel>>((ColorLabelcolor){returnDropdownMenuEntry<ColorLabel>(value:color,label:color.label,enabled:color.label!='Grey',style:MenuItemButton.styleFrom(foregroundColor:color.color,),);}).toList(),);}

content_copy

slideshowVideo:DropdownMenu (Widget of the Week)

TheSlider widget lets a user adjust a value by moving an indicator, such as a volume bar.

Configuration parameters for theSlider widget:

• value represents the slider's current value
• onChanged is the callback that gets triggered when the handle is moved
• min andmax establish minimum and maximum values allowed by the slider
• divisions establishes a discrete interval with which the user can move the handle along the track.

dart

double_currentVolume=1;​@overrideWidgetbuild(BuildContextcontext){returnSlider(value:_currentVolume,max:5,divisions:5,label:_currentVolume.toString(),onChanged:(doublevalue){setState((){_currentVolume=value;});},);}

content_copy

slideshowVideo:Slider, RangeSlider, CupertinoSlider (Widget of the Week)

menu_bookAPI Docs:SegmentedButton •DropdownMenu •Slider •Chip

There are several ways that your UI can allow toggling between values.

Provide an option to toggle a single value on and off. The functional logic behind these widgets are the same, as all 3 are built on top ofToggleableStateMixin, though each provides slight presentation differences.:

• Checkbox is a container that is empty when false or filled with a checkmark when true.
• Switch has a handle that is on the left when false and slides to the right when true.
• Radio is similar to aCheckbox in that it's a container that is empty when false, but filled in when true.

The configuration forCheckbox andSwitch contain:

• avalue that istrue orfalse
• and anonChanged callback which is triggered when the user toggles the widget

dart

boolisChecked=false;​@overrideWidgetbuild(BuildContextcontext){returnCheckbox(checkColor:Colors.white,value:isChecked,onChanged:(bool?value){setState((){isChecked=value!;});},);}

content_copy

dart

boollight=true;​@overrideWidgetbuild(BuildContextcontext){returnSwitch(// This bool value toggles the switch.value:light,activeThumbColor:Colors.red,onChanged:(boolvalue){// This is called when the user toggles the switch.setState((){light=value;});},);}

content_copy

ARadioGroup containsRadio buttons that allow the user to select between mutually exclusive values. When the user selects a radio button in a group, the other radio buttons are unselected.

• A particularRadio button'svalue represent that button's value.
• The selected value for aRadioGroup is identified by thegroupValue parameter.
• RadioGroup has anonChanged callback that gets triggered when users click it, likeSwitch andCheckbox.

dart

enumCharacter{musician,chef,firefighter,artist}​classRadioExampleextendsStatefulWidget{constRadioExample({super.key});​@overrideState<RadioExample>createState()=>_RadioExampleState();}​class_RadioExampleStateextendsState<RadioExample>{Character?_character=Character.musician;​voidsetCharacter(Character?value){setState((){_character=value;});}​@overrideWidgetbuild(BuildContextcontext){returnRadioGroup(groupValue:_character,onChanged:setCharacter,child:Column(children:<Widget>[ListTile(title:constText('Musician'),leading:Radio<Character>(value:Character.musician),),ListTile(title:constText('Chef'),leading:Radio<Character>(value:Character.chef),),ListTile(title:constText('Firefighter'),leading:Radio<Character>(value:Character.firefighter),),ListTile(title:constText('Artist'),leading:Radio<Character>(value:Character.artist),),],),);}}

content_copy

These convenience widgets are the same checkbox and switch widgets, but support a label (as aListTile).

dart

doubletimeDilation=1.0;bool_lights=false;​@overrideWidgetbuild(BuildContextcontext){returnColumn(children:[CheckboxListTile(title:constText('Animate Slowly'),value:timeDilation!=1.0,onChanged:(bool?value){setState((){timeDilation=value!?10.0:1.0;});},secondary:constIcon(Icons.hourglass_empty),),SwitchListTile(title:constText('Lights'),value:_lights,onChanged:(boolvalue){setState((){_lights=value;});},secondary:constIcon(Icons.lightbulb_outline),),],);}

content_copy

slideshowVideo:CheckboxListTile (Widget of the Week)

slideshowVideo:SwitchListTile (Widget of the Week)

menu_bookAPI Docs:Checkbox •CheckboxListTile •Switch •SwitchListTile •Radio

Widgets are provided so the user can select a date and time.

There is a set of dialogs that enable users to select a date or time, as you'll see in the following sections. With the exception of differing date types -DateTime for dates vsTimeOfDay for time - these dialogs function similarly, you can configure them by providing:

• a defaultinitialDate orinitialTime
• or aninitialEntryMode that determines the picker UI that's displayed.

This dialog allows the user to select a date or a range of dates. Activate by calling theshowDatePicker function, which returns aFuture<DateTime>, so don't forget to await the asynchronous function call!

dart

DateTime?selectedDate;​@overrideWidgetbuild(BuildContextcontext){vardate=selectedDate;​returnColumn(children:[Text(date==null?'You haven\\\'t picked a date yet.':DateFormat('MM-dd-yyyy').format(date),),ElevatedButton.icon(icon:constIcon(Icons.calendar_today),onPressed:()async{varpickedDate=awaitshowDatePicker(context:context,initialEntryMode:DatePickerEntryMode.calendarOnly,initialDate:DateTime.now(),firstDate:DateTime(2019),lastDate:DateTime(2050),);​setState((){selectedDate=pickedDate;});},label:constText('Pick a date'),)]);}

content_copy

TimePickerDialog is a dialog that presents a time picker. It can be activated by calling theshowTimePicker() function. Instead of returning aFuture<DateTime>,showTimePicker instead returns aFuture<TimeOfDay>. Once again, don't forget to await the function call!

dart

TimeOfDay?selectedTime;​@overrideWidgetbuild(BuildContextcontext){vartime=selectedTime;​returnColumn(children:[Text(time==null?'You haven\\\'t picked a time yet.':time.format(context),),ElevatedButton.icon(icon:constIcon(Icons.calendar_today),onPressed:()async{varpickedTime=awaitshowTimePicker(context:context,initialEntryMode:TimePickerEntryMode.dial,initialTime:TimeOfDay.now(),);​setState((){selectedTime=pickedTime;});},label:constText('Pick a time'),)]);}

content_copy

menu_bookAPI Docs:showDatePicker •showTimePicker

ADismissible is a widget that enables users to dismiss it by swiping. It has a number of configuration parameters, including:

• Achild widget
• AnonDismissed callback that is triggered when the user swipes
• Styling parameters such asbackground
• It's important to include akey object as well so that they can be uniquely identified from siblingDismissible widgets in the widget tree.

dart

List<int>items=List<int>.generate(100,(intindex)=>index);​@overrideWidgetbuild(BuildContextcontext){returnListView.builder(itemCount:items.length,padding:constEdgeInsets.symmetric(vertical:16),itemBuilder:(BuildContextcontext,intindex){returnDismissible(background:Container(color:Colors.green,),key:ValueKey<int>(items[index]),onDismissed:(DismissDirectiondirection){setState((){items.removeAt(index);});},child:ListTile(title:Text('Item${items[index]}',),),);},);}

content_copy

slideshowVideo:Dismissible (Widget of the Week)

starCheckpoint: Complete this tutorial on how toimplement swipe to dismiss using the dismissible widget.

menu_bookAPI Docs:Dismissible

This page features just a few of the common Material widgets that you can use for handling user input in your Flutter app. Check out theMaterial Widget library andMaterial Library API docs for a full list of widgets.

flutterDemo: See Flutter'sMaterial 3 Demo for a curated sample of user input widgets available in the Material library.

If the Material and Cupertino libraries don't have a widget that does what you need, check outpub.dev to find Flutter & Dart community-owned and maintained packages. For example, theflutter_slidable package provides aSlidable widget that is more customizable than theDismissible widget described in the previous section.

slideshowVideo:flutter_slidable (Package of the Week)

Have you scoured the widget libraries, pub.dev, asked your coding friends, and still can't find a widget that fits the user interaction that you're looking for? You can build your own custom widget and make it interactive usingGestureDetector.

starCheckpoint: Use this recipe as a starting point to create your owncustom button widget that canhandle taps.

slideshowVideo:GestureDetector (Widget of the Week)

menu_bookReference: Check outTaps, drags, and other gestures which explains how to listen for, and respond to, gestures in Flutter.

slideshowBonus Video: Curious how Flutter'sGestureArena turns raw user interaction data into human recognizable concepts like taps, drags, and pinches? Check out this video:GestureArena (Decoding Flutter)

If you're building a custom widget, annotate its meaning with theSemantics widget. It provides descriptions and metadata to screen readers and other semantic analysis-based tools.

slideshowVideo:Semantics (Flutter Widget of the Week)

menu_bookAPI Docs:GestureDetector •Semantics

Once you have finished building user interactions into your app, don't forget to write tests to ensure that everything works as expected!

These tutorials walk you through writing tests that simulate user interactions in your app:

starCheckpoint: Follow thistap, drag, and enter text cookbook article and learn how to useWidgetTester to simulate and test user interactions in your app.

bookmarkBonus Tutorial: Thehandle scrolling cookbook recipe shows you how to verify that lists of widgets contain the expected content by scrolling through the lists using widget tests.

This page was an introduction to handling user input. Now that you know how to handle input from app users, you can make your app even more interesting by adding external data. In the next section, you'll learn how to fetch data for your app over a network, how to convert data to and from JSON, authentication, and other networking features.

As this section of the website is evolving, wewelcome your feedback!