WKeyboardActions

A wrapper that renders a Done button and field-navigation toolbar above the keyboard for any group of input fields, with optional platform targeting and custom close widget.

Table of Contents

• Basic Usage
• Constructor
• Props
• Platform Targeting
• Navigation Between Fields
• Toolbar Styling
• Custom Close Button
• The Toolbar Occludes, and Says So
• Styling Examples
• Related Documentation

WKeyboardActions(
  focusNodes: [_nameFocus, _amountFocus],
  toolbarClassName: 'bg-gray-100 dark:bg-gray-800',
  child: Column(
    children: [
      WInput(focusNode: _nameFocus, placeholder: 'Jane Doe'),
      WInput(
        focusNode: _amountFocus,
        placeholder: '0.00',
        type: InputType.number,
      ),
    ],
  ),
)

Basic Usage

Create a FocusNode for each input field and pass them all in the focusNodes list. WKeyboardActions attaches listeners to every node and shows the toolbar as long as any one of them is focused.

class _MyFormState extends State {
  final _nameFocus = FocusNode();
  final _amountFocus = FocusNode();

  @override
  void dispose() {
    _nameFocus.dispose();
    _amountFocus.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return WKeyboardActions(
      focusNodes: [_nameFocus, _amountFocus],
      child: Column(
        children: [
          WInput(focusNode: _nameFocus, placeholder: 'Full Name'),
          WInput(
            focusNode: _amountFocus,
            placeholder: '0.00',
            type: InputType.number,
          ),
        ],
      ),
    );
  }
}

The toolbar is hosted in the ROOT Overlay, not the nearest one. It positions itself in screen terms (bottom: viewInsets.bottom, so it sits on top of the keyboard), and a nested Overlay is measured in its own box rather than the screen's. An app whose page host owns an Overlay inside a scroll view gives that overlay the height of the scrolled content, so a nearest-overlay toolbar would render hundreds of points below the viewport: present in the widget tree, absent from the screen. You need no Overlay of your own for this to work; MaterialApp and CupertinoApp both provide the root one.

Constructor

const WKeyboardActions({
  Key? key,
  required Widget child,
  required List focusNodes,
  String platform = 'all',
  bool nextFocus = true,
  String? toolbarClassName,
  Widget Function(FocusNode)? closeWidgetBuilder,
})

Props

Platform Targeting

The platform prop gates the toolbar to a specific OS. The most common value is 'ios', because iOS numeric keyboards have no built-in Done button.

WKeyboardActions(
  platform: 'ios',
  focusNodes: [_amountFocus],
  child: WInput(
    focusNode: _amountFocus,
    placeholder: '0.00',
    type: InputType.number,
  ),
)

Navigation Between Fields

When nextFocus: true (the default), the toolbar shows Previous and Next arrow buttons. They move focus to the previous or next node in the focusNodes list, in the order they were provided. The Previous button is disabled at the first field; the Next button is disabled at the last.

Set nextFocus: false to show only the Done button, which is useful for single-field forms.

WKeyboardActions(
  focusNodes: [_nameFocus, _emailFocus, _amountFocus],
  nextFocus: true,
  child: Column(
    children: [
      WInput(focusNode: _nameFocus, placeholder: 'Jane Doe'),
      WInput(focusNode: _emailFocus, placeholder: '[email protected]'),
      WInput(focusNode: _amountFocus, placeholder: '0.00'),
    ],
  ),
)

Toolbar Styling

Pass Wind bg-* utility classes via toolbarClassName to set the toolbar background. The dark: pair is required.

WKeyboardActions(
  toolbarClassName: 'bg-gray-100 dark:bg-gray-800',
  focusNodes: [_focusNode],
  child: myInputField,
)

When toolbarClassName is null, the toolbar uses Theme.of(context).colorScheme.surfaceContainerHighest.

Custom Close Button

Supply closeWidgetBuilder to replace the default "Done" label with any widget. The builder receives the currently-focused FocusNode, which you can call unfocus() on.

WKeyboardActions(
  focusNodes: [_focusNode],
  closeWidgetBuilder: (node) => WButton(
    onTap: node.unfocus,
    className: 'bg-blue-600 text-white px-4 py-1.5 rounded-md text-sm font-medium',
    child: const WText('Save & Close', className: 'text-white text-sm font-medium'),
  ),
  child: myInputField,
)

The Toolbar Occludes, and Says So

The toolbar is drawn in the root overlay at bottom: viewInsets.bottom, which puts it directly ON TOP of the keyboard. The engine reports the keyboard through viewInsets and knows nothing about the bar, so the region a focused field has to clear is the keyboard PLUS the toolbar, and anything reading viewInsets alone reserves too little. A field that cleared the keyboard came out from under it and straight under the bar.

WKeyboardActions measures its own bar and publishes the height to its subtree:

final double toolbar = WKeyboardToolbarInset.of(context);

Zero when no bar is up, which covers every platform the widget is gated off and every moment nothing is focused. WInput already consumes it, so a plain field inside a WKeyboardActions needs nothing; reach for it in a widget of your own that positions something against the keyboard.

The height is measured rather than assumed, because the row is built from IconButtons whose size comes from the ambient theme and toolbarClassName can change the padding around them.

Styling Examples

Minimal (single field, iOS only)

WKeyboardActions(
  platform: 'ios',
  nextFocus: false,
  focusNodes: [_amountFocus],
  toolbarClassName: 'bg-white dark:bg-gray-900',
  child: WInput(
    focusNode: _amountFocus,
    placeholder: '0.00',
    type: InputType.number,
  ),
)

Multi-field form with custom toolbar color

WKeyboardActions(
  focusNodes: [_nameFocus, _emailFocus, _amountFocus],
  toolbarClassName: 'bg-blue-50 dark:bg-blue-950',
  child: Column(
    children: [
      WInput(focusNode: _nameFocus, placeholder: 'Jane Doe'),
      WInput(focusNode: _emailFocus, placeholder: '[email protected]'),
      WInput(focusNode: _amountFocus, placeholder: '0.00'),
    ],
  ),
)

Custom close widget

WKeyboardActions(
  focusNodes: [_focusNode],
  toolbarClassName: 'bg-emerald-50 dark:bg-emerald-900',
  closeWidgetBuilder: (node) => TextButton.icon(
    onPressed: node.unfocus,
    icon: const Icon(Icons.check_circle_outlined),
    label: const Text('Done'),
  ),
  child: myInputField,
)

Related Documentation

• WInput - The unstyled text input widget
• WFormInput - Form-bound WInput with validator
• WDiv - General-purpose container for laying out form fields