# TextField

A form control for single-line or multi-line text input.

## Usage

Use standalone.

```svelte
<TextField {...props} />
```

## Anatomy

The `class` attribute values represent part names, and `conditional` indicates elements that are rendered conditionally. Other attributes represent their corresponding props.

```svelte
<div class="whole">
  <div class="top" conditional>
    <label class="label" conditional>
      {label}
      <span class="extra" conditional>{extra}</span>
    </label>
    <span class="aux" conditional>{aux}</span>
  </div>
  <div class="middle">
    <span class="left" conditional>{left}</span>
    {#if type === "textarea"}
      <textarea class="main" {...rest} bind:value bind:this={element}></textarea>
    {:else}
      <input class="main" {...rest} {type} bind:value bind:this={element} />
      <datalist conditional>
        {#each options as option}
          <option value={option}></option>
        {/each}
      </datalist>
    {/if}
    <span class="right" conditional>{right}</span>
  </div>
  <div class="bottom" conditional>{bottom}</div>
</div>
```

## Props

| Name          | Type                  | Default   | Description                                                               |
| ------------- | --------------------- | --------- | ------------------------------------------------------------------------- |
| `label`       | `string`              | -         | Field label                                                               |
| `extra`       | `string`              | -         | Extra text shown with the label                                           |
| `aux`         | `Snippet`             | -         | Auxiliary content; receives value, variant, and control element           |
| `left`        | `Snippet`             | -         | Content before the control; receives value, variant, and control element  |
| `right`       | `Snippet`             | -         | Content after the control; receives value, variant, and control element   |
| `bottom`      | `string`              | -         | Bottom message                                                            |
| `reserve`     | `boolean`             | `false`   | Renders the bottom element even without a message to prevent layout shift |
| `value`       | `string`              | -         | Bindable field value                                                      |
| `type`        | `<enum>`              | `"text"`  | Control type, including textarea mode                                     |
| `options`     | `SvelteSet`           | -         | String datalist suggestions; ignored when `type` is `"textarea"`          |
| `validations` | `TextFieldValidation` | -         | Validation functions for input values                                     |
| `attach`      | `Attachment`          | -         | Svelte attachment on the control                                          |
| `element`     | `HTMLInputElement`    | -         | Bindable control element                                                  |
| `styling`     | `SVSClass`            | -         | Styling override                                                          |
| `variant`     | `SVSVariant`          | `NEUTRAL` | Bindable variant                                                          |
| `cols`        | `number`              | -         | Textarea column count                                                     |
| `rows`        | `number`              | -         | Textarea row count                                                        |
| `wrap`        | `<enum>`              | -         | Textarea wrapping behavior                                                |
Other `HTMLInputAttributes` are passed to `<input>`/`<textarea>` via rest props; `class` is merged onto the root.

## Styling

To learn more, see [Styling](/docs/styling).

### Variant Management

In the initial state or when there is no input value, `neutral` is applied. After a value is entered, the variant switches to `active` if validation succeeds, or to `inactive` if validation fails. When validating the form, `inactive` is applied when validation fails. If the `variant` prop is specified, the specified value is applied instead of `neutral`.

### Default Class Name

`svs-text-field`

## Accessibility

### ARIA Roles and Attributes

The component applies these automatically:

- Field (`whole` `<div>`): `role="group"` and `aria-labelledby` pointing to the label part when label text is present.
- Input (`main` `<input>`): `aria-describedby`, `aria-invalid`, and `aria-errormessage` from the validation message wiring.
- Message (`bottom`): `role="alert"` when the field is inactive and showing an error message.

Provide `label` text for the field's accessible name; the component wires that label to the group and control instead of requiring an author-passed `aria-label`.

### Standards Basis

TextField is built on a native `<input>`, so keyboard and assistive-technology support follows the browser standard for text inputs. See the [Concepts standards-first guidance](/docs/concepts) for the library's approach.

## Exports

### Types

```ts
type TextFieldValidation = SVSFieldValidation<string, HTMLInputElement | HTMLTextAreaElement>;
interface TextFieldProps extends Omit<HTMLInputAttributes, "type" | "value"> {
  label?: string;
  extra?: string;
  aux?: Snippet<[string, string, HTMLInputElement | HTMLTextAreaElement | undefined]>; // Snippet<[value,variant,element]>
  left?: Snippet<[string, string, HTMLInputElement | HTMLTextAreaElement | undefined]>; // Snippet<[value,variant,element]>
  right?: Snippet<[string, string, HTMLInputElement | HTMLTextAreaElement | undefined]>; // Snippet<[value,variant,element]>
  bottom?: string;
  reserve?: boolean; // (false)
  value?: string; // bindable
  type?: "text" | "textarea" | "email" | "password" | "search" | "tel" | "url"; // ("text")
  options?: SvelteSet<string> | Set<string>;
  validations?: TextFieldValidation[];
  attach?: Attachment<HTMLInputElement | HTMLTextAreaElement>;
  element?: HTMLInputElement | HTMLTextAreaElement; // bindable
  styling?: SVSClass;
  variant?: SVSVariant; // bindable (VARIANT.NEUTRAL)
  // class & other input/textarea attributes are passed to the control via ...rest
  cols?: number | undefined | null; // textarea
  rows?: number | undefined | null; // textarea
  wrap?: "hard" | "soft" | "off" | undefined | null; // textarea
}
type TextFieldReqdProps = never;
type TextFieldBindProps = "value" | "variant" | "element";
```

### Others

No additional exports are available.

## Examples

The example code uses Tailwind CSS along with `SVSClass`.

### Basic

**Code**

```svelte src=TextFieldBasic.svelte
<script lang="ts">
  import { TextField } from "svseeds";

  const styling = {
    label: "font-bold",
    middle: "mt-1",
    main: "px-2 py-1 w-40 rounded-sm border outline-hidden",
    bottom: "mt-1 text-xs",
  };
  const myProps = {
    label: "Text Field",
    bottom: "Enter your text",
    styling,
  };
</script>

<div class="flex flex-col sm:flex-row gap-4">
  <TextField {...myProps} />
  <TextField type="textarea" {...myProps} />
</div>
```
### With Interactive Variant

**Code**

```svelte src=TextFieldPract.svelte
<script lang="ts">
  import { TextField } from "svseeds";
  import Apple from "@lucide/svelte/icons/apple";

  let { variant = $bindable() } = $props();
  const variantStyle = {
    neutral: "border-gray-400",
    active: "border-teal-500",
    inactive: "border-red-500",
    blue: "border-blue-500",
    yellow: "border-yellow-500",
    sky: "border-sky-500",
  };
  const styling = {
    label: {
      base: "flex items-center font-bold",
      inactive: "text-red-500",
    },
    extra: "ps-1 text-gray-400 text-sm",
    middle: {
      base: "flex gap-2 mt-1 px-2 border-b",
      ...variantStyle,
    },
    main: "w-40 outline-hidden",
    bottom: {
      base: "mt-1 text-xs",
      inactive: "text-red-500",
    },
  };
  const myProps = {
    label: "Favorite Fruit",
    extra: "(optional)",
    bottom: "Enter your favorite",
    validations: [({ value }: { value: string }) => (value.toLowerCase() === "banana" ? "Banana is not allowed" : "")],
    styling,
  };
</script>

<TextField bind:variant {...myProps}>
  {#snippet left()}
    <Apple class="size-5" />
  {/snippet}
</TextField>
```