Form Component

How It Works

The FormComponent integrates directly with Atlas Forms via the FormRenderer from the player-components-react package. When the interaction is received:

Form Payload Schema

interface FormPayload {
  /** Atlas Form ID — the form schema to render */
  formId: number;

  /** Pre-fill values — mapped to form field keys */
  initialValues?: Record<string, unknown>;

  /** Submit button label (default: "Submit") */
  submitLabel?: string;

  /** Cancel button label (default: "Cancel") */
  cancelLabel?: string;
}

Response Schema

// Outcome: "submitted"
// Data: all submitted form field values
interface FormResponseData {
  [fieldKey: string]: unknown;
}

// Example response data
{
  "recipientName": "Jane Smith",
  "country": "US",
  "address": "123 Main St",
  "city": "Springfield",
  "postalCode": "62701"
}

Server-Side Usage

// Server — send a form interaction
var request = new InteractionRequest {
  Type = InteractionTypes.Form,
  TargetUserId = userId,
  Title = "Enter Shipping Details",
  Description = "Please provide the shipping address for this order.",
  Payload = new FormPayload {
    FormId = 13042, // Atlas Form ID for "Shipping Address Form"
    InitialValues = new Dictionary<string, object> {
      { "recipientName", currentUser.FullName },
      { "country", "US" }
    },
    SubmitLabel = "Save Shipping Details"
  },
  TimeoutMs = 600_000 // 10 minutes
};

var response = await _publisher.PublishAndWaitAsync(request, ct);

if (response.Outcome == "submitted")
{
    var shippingData = response.Data?.Deserialize<Dictionary<string, object>>();
    await _orderService.SetShippingAddressAsync(orderId, shippingData, ct);
}

Form Validation

Atlas Form validation rules (required fields, format validation, conditional fields) are enforced by the FormRenderer on the client side. The form cannot be submitted until all validation rules pass. The FormComponent does not send the response until the form submission event fires from FormRenderer.

Form Interaction vs. Atlas Form Player