NgAIPrompt — AI prompt interface

Manual · Getting started · Code examples · Models

When to use it

Compose requests, inspect responses and manage retries, history and feedback.

Appearance and live example

Try the Blazor example · Flutter example code

The live Blazor preview is embedded above. Use Reset to restore its initial state. Flutter implementation code is provided below; run the Flutter gallery from the installed developer workspace. Dialogs and drawers start closed; use their Open button. Tooltips appear on hover or keyboard focus.

Behavior and practical rules

Provider contract

Blazor Generate is Func<string,CancellationToken,Task<string>>; Flutter generate is NgPromptGenerator: Future<String> Function(String,NgPromptCancellation). The handler receives a captured, trimmed prompt and returns complete response text. Without it the input is disabled. The example/gallery uses a deterministic delayed local handler, not an AI model.

The application owns authentication, model choice, rate limits, timeouts and provider calls. Keep provider credentials on your backend. In Blazor pass CancellationToken into the HTTP/AI client. In Flutter connect cancellation.whenCancelled to transport cancellation; isCancelled and throwIfCancelled detect cancellation. Checking after await stops result processing, not the remote request or billing. The component itself makes no network requests.

Draft and request lifecycle

Value/value and change callbacks control the draft. Maximum prompt: 8000 UTF-16 units. Up to 8 nonempty suggestions, each at most 200 units. Suggestions fill the draft without sending. Enter inserts a newline; Send submits. Duplicate submission is blocked while busy. The user cannot edit during a request, but an external Value replacement changes the next draft, not the captured request.

Cancel immediately releases the UI and signals cancellation. A new request may start immediately. Even if an older handler ignores cancellation, its late result/error cannot enter history or replace newer state. Disposal, ReadOnly, GenerationReadOnly or removing the handler also cancels pending work. ReadOnly keeps history browsing/copying available. Transport cancellation is the application's responsibility.

Provider exceptions show a generic Generation failed. Try again. message; log details in your handler. Retry request uses the last failed prompt even if the draft changed. Empty/whitespace responses and responses over 32000 UTF-16 units are errors. Previous successful history survives failures. Timeouts belong to the application.

Responses and events

The last 20 successful responses are kept in memory; oldest entries are evicted. IDs increase throughout the component session, including after Clear history. Selecting history changes the displayed response. Regenerate runs that response's original prompt. Clear removes history/selection/votes and cancels work in the public session API; the UI button is disabled while busy. History is not durable and is lost on component disposal.

NgPromptResponse contains Id/id, Prompt/prompt and Text/text. OnCompleted fires once for each accepted successful response, never for cancellation/failure. NgPromptFeedback contains the response and Helpful/helpful: true, false or null for a cleared vote. Clicking the same vote toggles it off; votes do not call the provider. Callback exceptions belong to the host application.

Responses render as plain text, with no HTML/Markdown execution. Copy response uses the browser/platform clipboard; when unavailable, select the text manually. Clipboard permissions and secure-context rules depend on the host. There are no attachments, speech, command templates, streaming, provider SDKs, model picker, durable conversations or automatic moderation.

Session API and integration

NgPromptSession exposes read-only Responses/responses, Selected/selected, IsBusy/isBusy, Error/error and Status/status. RunAsync/run invokes a handler; Cancel/cancel invalidates pending work; Select/select changes selection; Clear/clear resets history; Dispose/dispose ends the session. Blazor Changed and Flutter ChangeNotifier report state changes. Use it on the UI thread, dispose it in its owner, and do not mutate response collections. The component owns its own session; use the public session only when building a separate custom interface. Native mobile and full accessibility certification remain separate.

Independent permissions (0.45)

GenerationReadOnly/generationReadOnly disables composition, suggestions, Send, Retry and Regenerate and cancels pending work. HistoryReadOnly/historyReadOnly prevents Clear history; reading, selecting and copying responses remain available. FeedbackReadOnly/feedbackReadOnly prevents voting. All default to false. ReadOnly applies all three restrictions. Missing generation handlers disable suggestions as well as composition; missing feedback handlers disable voting, with no local-only votes.

Action handlers recheck current permissions and disposal, not just button appearance. Regenerate and feedback require the captured response still to be selected; removed suggestions and evicted/cleared history actions are ignored. Feedback remains available during generation for the selected previous response when permitted. History selection and copy remain available under every lock. The locks control UI behavior; application services must enforce their own authorization.

Blazor example

<div class="ng-prompt-actions">
 <NgButton OnClick="()=>generationLocked=!generationLocked">Toggle generation lock</NgButton>
 <NgButton OnClick="()=>historyLocked=!historyLocked">Toggle history lock</NgButton>
 <NgButton OnClick="()=>feedbackLocked=!feedbackLocked">Toggle feedback lock</NgButton>
</div>
<NgAIPrompt Label="Assistant" @bind-Value="prompt" Generate="Generate"
 GenerationReadOnly="generationLocked" HistoryReadOnly="historyLocked" FeedbackReadOnly="feedbackLocked"
 Suggestions="suggestions" OnCompleted="Completed" OnFeedback="Feedback"/>
<p>Completed: @completed · Feedback events: @feedbackCount</p>
@code {
 private string prompt="Draft a meeting agenda";
 private bool generationLocked,historyLocked,feedbackLocked;
 private int completed,feedbackCount;
 private string[] suggestions=["Draft a meeting agenda","Suggest next steps"];
 private async Task<string> Generate(string text,CancellationToken cancellation) {
  await Task.Delay(1200,cancellation);
  return $"Local example response to: {text}"; // Connect your application service here.
 }
 private void Completed(NgPromptResponse response){completed++;}
 private void Feedback(NgPromptFeedback feedback){feedbackCount++;}
}

Flutter example

String prompt = 'Draft a meeting agenda';
bool generationLocked = false, historyLocked = false, feedbackLocked = false;
int completed = 0, feedbackCount = 0;
Future<String> generate(String text, NgPromptCancellation cancellation) async {
  await Future<void>.delayed(const Duration(milliseconds: 1200));
  cancellation.throwIfCancelled();
  return 'Local example response to: $text'; // Connect your application service here.
}
Widget build(BuildContext context) => Column(crossAxisAlignment: CrossAxisAlignment.stretch, children: [
 Wrap(spacing: 8, runSpacing: 8, children: [
  NgButton(onPressed: () => setState(() => generationLocked = !generationLocked), child: const Text('Toggle generation lock')),
  NgButton(onPressed: () => setState(() => historyLocked = !historyLocked), child: const Text('Toggle history lock')),
  NgButton(onPressed: () => setState(() => feedbackLocked = !feedbackLocked), child: const Text('Toggle feedback lock')),
 ]),
 NgAIPrompt(label: 'Assistant', value: prompt, onChanged: (v) => setState(() => prompt = v),
  generate: generate, generationReadOnly: generationLocked, historyReadOnly: historyLocked,
  feedbackReadOnly: feedbackLocked,
  suggestions: const ['Draft a meeting agenda', 'Suggest next steps'],
  onCompleted: (_) => setState(() => completed++), onFeedback: (_) => setState(() => feedbackCount++)),
 Text('Completed: $completed · Feedback events: $feedbackCount'),
]);

Blazor parameters and events

Names are case-sensitive. ? permits null. EditorRequired parameters are marked required; other values use the initializer or CLR default.

Flutter parameters and events

required marks a mandatory argument even if its type is nullable. key is the standard Flutter Key. The exact constructor below specifies defaults.

const NgAIPrompt({
    super.key,
    this.label = 'AI prompt',
    this.value = '',
    this.suggestions = const [],
    this.generate,
    this.readOnly = false,
    this.generationReadOnly = false,
    this.historyReadOnly = false,
    this.feedbackReadOnly = false,
    this.onChanged,
    this.onCompleted,
    this.onFeedback,
  });

Integration and troubleshooting

If the UI does not update, confirm that the parent stores callback values and passes them back. Blazor event handlers need interactive rendering; Flutter requires setState or a state manager. Submit form data only after successful validation.

Check accessible labels, empty/invalid states, disabled actions and narrow layouts. Keyboard support is not full screen-reader certification. Current visual verification targets Web in visible Chrome on Linux/iMac; native mobile platforms are a separate phase.

Source and complete examples

• Blazor source
• Flutter source
• Galleries and launch commands
• Capability matrix

API declarations are generated from current source. Curated examples and behavior live in scripts/manual_content.py; regenerate with python3 scripts/generate_manual.py.