---
layout: "layouts/DocLayout.astro"
title: Forms
description: Documentation for the Forms API for spotube plugins
order: 1
---

Spotube provides a Forms API that allows plugin developers to create and manage forms within the Spotube application.

## Usage

Following will show a form with 2 text fields and text in between them:

```hetu_script
import "module:spotube_plugin" as spotube

spotube.SpotubeForm.show(
  "The form page title",
  [
    {
      objectType: "input",
      id: "name",
      variant: "text",
      placeholder: "Enter your name",
      required: true,
    }.toJson(),
    {
      objectType: "input",
      id: "password",
      variant: "password", // This will obfuscate the input
      placeholder: "Enter your password",
      required: true,
    }.toJson(),
    {
      objectType: "text",
      text: "This is some text after the two fields.",
    }.toJson(),
  ]
).then((result) {
  // Handle the result
  print(result)
})
```

The method `spotube.SpotubeForm.show` takes a title and a list of form field declaration map. The map should be, well obviously a `Map`.
Following are field map properties:

| Property       | Type              | Description                                                                        |
| -------------- | ----------------- | ---------------------------------------------------------------------------------- |
| `objectType`   | `text` or `input` | Type of the object, should be `text` for text fields and `input` for input fields. |
| `id`           | `String`          | Unique identifier for the field. (`input` type only)                               |
| `variant`      | `String`          | Variant of the field, can be `text`, `password` or `number`. (`input` type only)   |
| `placeholder`  | `String`          | Optional placeholder text for the field. (`input` type only)                       |
| `required`     | `Boolean`         | Whether the field is required or not. (`input` type only)                          |
| `defaultValue` | `String`          | Optional default value for the field. (`input` type only)                          |
| `regex`        | `String`          | Optional regex pattern to validate the input. (`input` type only)                  |
| `text`         | `String`          | Optional text for `text` object type. (Only applicable for `text` type)            |

The method `spotube.SpotubeForm.show` returns a following format:

```json
[
  {
    "id": "name",
    "value": "John Doe"
  },
  {
    "id": "password",
    "value": "12345678"
  }
]
```