Build Custom Inputs with Flutter's FormField Widget
FormField is a state wrapper, not a UI widget, that turns any widget into a validatable form input. Use it for custom inputs like sliders or star ratings that must integrate with a Form. The footgun is forgetting to supply the UI via its builder.
Why it exists
Flutter provides TextFormField for text, but forms often need more complex inputs like custom sliders, date pickers, or even signature pads. FormField exists to provide a standard way to manage the state (value, error, dirty status) for any widget, allowing it to integrate seamlessly into a Form.
The mental model
Think of FormField as a headless controller for a form input. It doesn't draw anything on the screen itself. Instead, it holds the value, the validation logic, and the error state, and exposes this state to a UI widget you provide via its builder function. It's the "brain" that makes a simple widget "form-aware".
How it works
You instantiate a FormField and provide a builder function. This function receives a FormFieldState object as its argument. Inside the builder, you return the widget you want the user to interact with, like a row of Icons for a star rating. You use the state object to read the current value (state.value), display errors (state.errorText), and update the value when the user interacts with your widget (state.didChange(newValue)). The validator function you provide is called to check the value, and onSaved is called when Form.save() is invoked.
When to use it
Use FormField whenever you need a custom input that's not a standard text box. Examples include a slider for a price range, a custom toggle switch with complex state, a star rating selector, or a color picker. It's the correct way to make these custom widgets participate in form-wide validation, saving, and resetting.
When not to use it
Don't use FormField for simple text input; TextFormField is a pre-built, convenient implementation for that exact purpose. Also, if your input doesn't need to be part of a larger form, doesn't require validation, and its state can be managed locally, using a raw StatefulWidget might be simpler.
One canonical example
To create a custom boolean switch, the FormField would hold a bool value. Its builder would return a Switch widget. The Switch's value property would be set to state.value, and its onChanged callback would call state.didChange(newValue). This connects the UI of the Switch to the state management of the FormField, making it a submittable part of a Form.
Interview question
For a custom star rating input that must integrate with a Flutter Form for validation and saving, which widget serves as the most appropriate foundation?
- a.A ValueListenableBuilder, to reactively update the star display based on a rating value.
- b.A StatefulWidget, to manage the star rating's visual state and user interactions.
- c.A FormField, utilizing its builder to render the stars and manage form-specific state.Correct
- d.A TextFormField, adapted to display stars and accept numerical input.
Why? this is the answer
FormField is specifically designed to wrap custom input widgets, like a star rating, enabling them to participate in form-wide validation, saving, and state management via its builder function. While a StatefulWidget is used for managing a widget's internal UI state, it does not inherently provide the integration with a Form's validation and saving mechanisms that FormField offers.
Just read this? Test yourself on what you have been reading.
Read the original → api.flutter.dev
Put your scrolling time to good use
Learn one idea, try a quiz and save useful cards for revision. Tezvyn makes it easy to learn and stay current in your tech field, a few minutes at a time.
The iPhone app is on the way
We are building it. Until it lands, nothing here is held back from you: every interview card, your saved cards, streaks and the job board all work in Safari, plus hundreds of free practice quizzes of thirty questions each. Sign in and it all carries over to the app the day it arrives.
Want it as an icon? Tap Share at the bottom of Safari, then Add to Home Screen. It opens full screen and the cards you have read stay available offline.
We are hiring for this. Open roles that interview on flutter — each one lists the topics its interview covers.
See open roles