flutter_message_composer #

An adaptive Flutter message composer for chat and messaging experiences. It provides multiline text input, configurable actions, typed submissions, and tap-or-hold audio recording with playback previews. It is independent of networking, storage, and state management.

The package currently targets Android and iOS.

Features #

• Compact input that animates into a multiline composer.
• Configurable attachment menu and prompt actions.
• Text, attachment, and recorded-audio submission payloads.
• Tap to manage a recording or hold to record and send on release.
• Slide toward cancel to discard a held recording, or upward to lock it and continue hands-free without sending on release.
• Stop, play, pause, resume, and replay audio before sending.
• Tabular MM:SS recording and playback times beside the waveform.
• Playback progress and theme-aware recording-lock feedback.
• Disabled and sending states.
• Theme-aware defaults with optional colors, shapes, icons, and tooltips.
• A customizable suggestion area for mentions, hashtags, commands, quick replies, or any other contextual content.
• Callbacks for typing, recording lifecycle, permission denial, and errors.
• Async hook before microphone startup for host-owned sounds or telemetry.
• Typed recording lifecycle events for host-owned orchestration.
• An injectable recorder contract for custom native or DSP-backed capture.
• A lazily created, injectable audio preview player.
• No dependency on a chat backend or state-management package.

Installation #

Add the published package to pubspec.yaml:

dependencies:
  flutter_message_composer: ^0.3.0

Platform setup #

Audio recording uses the flutter_recorder package. The default recorder writes voice-note friendly mono WAV files at 22.05 kHz with 16-bit PCM samples, matching flutter_recorder's native defaults. On iOS it uses the generic PlayAndRecord preset so microphone startup is not left behind a playback-only audio session. Native silence detection is available through MessageComposerAudioRecorderConfig, but it is opt-in because flutter_recorder requires PCMFormat.f32le for silence detection while 16-bit PCM WAV is the safest default for local playback.

Android requires the microphone permission in android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.RECORD_AUDIO" />

iOS requires version 12.0 or newer and a usage description in ios/Runner/Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>Audio messages require access to the microphone.</string>

Usage #

import 'package:flutter/material.dart';
import 'package:flutter_message_composer/flutter_message_composer.dart';

final controller = TextEditingController();
final focusNode = FocusNode();

MessageComposer(
  controller: controller,
  focusNode: focusNode,
  hintText: 'Message',
  sendTooltip: 'Send',
  attachTooltip: 'Attachments',
  recordTooltip: 'Record audio',
  suggestions: activeSuggestions.isEmpty
      ? null
      : SuggestionsList(
          suggestions: activeSuggestions,
          onSelected: handleSuggestion,
        ),
  menuActions: [
    ChatInputMenuAction(
      id: 'photo',
      label: 'Photo',
      icon: const Icon(Icons.image_outlined),
      onPressed: pickPhoto,
    ),
  ],
  menuPadding: const EdgeInsets.all(6),
  attachments: selectedAttachments,
  onChanged: handleTyping,
  onSend: (submission) {
    if (submission.hasAudio) {
      uploadAndSendAudio(submission.audio!);
      return;
    }

    sendMessage(
      text: submission.text,
      attachments: submission.attachments,
    );
  },
)

The suggestions property accepts a widget for displaying and selecting suggestions. Pass null when none are active and the area collapses automatically. The controller property accepts any TextEditingController, including specialized token-aware controllers. No text parser is required by this package.

The caller owns attachment picking, uploads, message creation, retries, and clearing the text controller after a submission is accepted. Pass sending: true to temporarily lock the composer while an operation is in progress.

The default recorder uses flutter_recorder. To customize capture format, silence handling, input presets, or audio processing, provide a MessageComposerAudioRecorderConfig or implement MessageComposerRecorder and return an isolated instance with audioRecorderFactory. The composer owns and disposes the returned backend.

MessageComposerAudioRecorderConfig.bestCompatible is the package default and records WAV files, which is the safest option for local preview/playback and services that accept standard audio uploads. Services that prefer smaller compressed voice notes can opt into Ogg Opus:

MessageComposer(
  controller: controller,
  focusNode: focusNode,
  audioRecorderFactory: () => MessageComposerAudioRecorder(
    config: MessageComposerAudioRecorderConfig.compressedOpus,
  ),
  onSend: handleSubmission,
)

Use onBeforeStartRecording for host-owned work that must finish before the microphone opens, such as playing a mic-opened sound. Use onRecordingEvent to react to typed phases such as permission checking, preparing, recording, locked, stopping, stopped, canceling, canceled, sending, sent, and failed.

Audio workflows #

• Tap the microphone: record until Stop, Send, or Cancel is pressed.
• Hold the microphone: record and send once when the same finger releases.
• Slide toward Cancel: discard immediately after the horizontal threshold. This direction is left in left-to-right layouts and right in right-to-left layouts, matching the cancel button.
• Slide upward: lock recording. Releasing the finger does not send; Stop, Send, and Cancel remain available.
• Stop: show Play and the recording's total duration.
• Play / Pause: listen before sending, resume from the paused position, or replay from the start after completion. Playback never submits audio.

The time before the waveform is elapsed recording time, current playback time while playing or paused, and total duration while stopped or completed. Minutes and seconds have at least two digits (01:03); recordings longer than an hour keep their total minutes (61:03).

Sending or canceling stops the preview first. Canceling or removing the composer discards its unsent recording. Once onSend receives an audio submission, the callback recipient owns that file and is responsible for its eventual cleanup. Releasing while permission or microphone startup is pending preserves the user's send, cancel, or lock intent without duplicate submissions.

Customization #

The new options are optional. Existing MessageComposer calls gain previews and recording gestures without additional setup.

MessageComposer(
  controller: controller,
  focusNode: focusNode,
  hintText: 'Message',
  recordingCancelDragDistance: 96,
  recordingLockDragDistance: 80,
  enableRecordingHaptics: true,
  recordingTimerStyle: const TextStyle(fontWeight: FontWeight.w600),
  cancelRecordingTooltip: 'Cancel',
  stopRecordingTooltip: 'Stop recording',
  playRecordingTooltip: 'Play audio',
  pauseRecordingTooltip: 'Pause audio',
  sendRecordingTooltip: 'Send audio',
  lockRecordingLabel: 'Lock recording',
  recordingLockedLabel: 'Recording locked',
  onRecordingLocked: handleRecordingLocked,
  onAudioPreviewError: handlePreviewError,
  onSend: handleSubmission,
)

Use playRecordingButtonIcon and pauseRecordingButtonIcon to replace the default icons, alongside the existing cancel, stop, and send icon overrides. The timer style merges with the theme and tabular-digit defaults. Gesture distances are positive logical pixels. Light-impact feedback confirms that a held recording has started and when a cancel or lock threshold is reached. Start feedback waits for microphone permission and successful capture; it is not emitted for failed starts or recordings already queued to send or cancel. Haptics can be disabled with enableRecordingHaptics: false.

Silence detection is disabled by default. Enable it with MessageComposerAudioRecorderConfig, set pcmFormat: PCMFormat.f32le, and opt into pauseRecordingOnSilence only when the host app wants to skip silent segments while writing the file. Use the config to change the silence threshold, required silent duration, pre-roll, recording format, sample rate, channel count, or platform input preset. Setting enableRecordingHaptics: false disables the composer's gesture feedback.

Previews use audioplayers. For another backend, implement MessageComposerPlayer and supply audioPlayerFactory. Report position changes and playback states, including pauses caused by native interruptions and completion. The composer owns the player but creates it only when the first preview is requested. onAudioPreviewError handles preview failures separately from capture errors and leaves the audio available to retry, send, or discard.

Recording labels have English defaults. Set the label and tooltip parameters to provide localized text. See example/lib/main.dart for a complete usage example.

Scope #

flutter_message_composer is a presentation component. It does not prescribe a message model, networking client, storage layer, or state-management solution. Submissions and lifecycle callbacks provide the integration points.