# TagsInputField

A form control for inputting and managing multiple tags or keywords.

## Usage

Use standalone, or wrap `TagsInput` to share state.
```svelte
<TagsInputField {...props} />

<TagsInputField {...props}>
  <TagsInput {...props} />
</TagsInputField>
```

## 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 children}{@render children()}{:else}<TagsInput />{/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 values, variant, and input element |
| `left` | `Snippet` | - | Content before the inner input; receives values, variant, and input element |
| `right` | `Snippet` | - | Content after the inner input; receives values, variant, and input element |
| `bottom` | `string` | - | Bottom message |
| `reserve` | `boolean` | `false` | Renders the bottom element even without a message to prevent layout shift |
| `values` | `string[]` | - | Bindable tag values |
| `constraints` | `TagsInputFieldConstraint[]` | - | Constraint functions used to restrict tag values |
| `validations` | `TagsInputFieldValidation[]` | - | Validation functions used to validate tag values |
| `name` | `string` | - | The `name` attribute for form submission |
| `element` | `HTMLInputElement` | - | Bindable input element |
| `styling` | `SVSClass` | - | Styling override |
| `variant` | `SVSVariant` | `NEUTRAL` | Bindable variant |
| `tagsInput` | `TagsInputProps` | - | Props for the default inner `TagsInput` when no `children` are supplied; ignored if a child control is provided |
| `children` | `Snippet` | - | Use the compound form to provide a child `TagsInput` that shares the field state |
Count limits are now expressed as `validations` or `constraints` functions, such as a minimum through `validations: [({ value }) => value.length < N ? msg : ""]` or a maximum through `constraints: [({ values }) => values.length >= N ? msg : ""]`. Element ordering is now controlled by CSS `order` when needed.

## Styling

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

### Variant Management

In the initial state or when there is no input value, `neutral` is applied. If constraints do not allow the input, `inactive` is applied. After a value is entered, the variant switches to `active` if validation succeeds, or remains `neutral` temporarily if validation fails. During form validation, `inactive` is applied when validation fails. If the `variant` prop is specified, the specified value is used instead of `neutral`.

### Default Class Name

`svs-tags-input-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.
- 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 instead of requiring an author-passed `aria-label`. Tags-input ARIA and keyboard behavior for the default control are documented on [TagsInput](/docs/tags-input); the field threads its error-message id to that control.

## Exports

### Types

```ts
type TagsInputFieldConstraint = SVSFieldConstraint;
type TagsInputFieldValidation = SVSFieldValidation<string[]>;
interface TagsInputFieldProps {
  label?: string;
  extra?: string;
  aux?: Snippet<[string[], string, HTMLInputElement | undefined]>; // Snippet<[values,variant,element]>
  left?: Snippet<[string[], string, HTMLInputElement | undefined]>; // Snippet<[values,variant,element]>
  right?: Snippet<[string[], string, HTMLInputElement | undefined]>; // Snippet<[values,variant,element]>
  bottom?: string;
  reserve?: boolean; // (false)
  values?: string[]; // bindable
  constraints?: TagsInputFieldConstraint[];
  validations?: TagsInputFieldValidation[];
  name?: string;
  element?: HTMLInputElement; // bindable
  styling?: SVSClass;
  variant?: SVSVariant; // bindable (VARIANT.NEUTRAL)
  tagsInput?: Omit<TagsInputProps, TagsInputReqdProps | TagsInputBindProps | "ariaErrMsgId" | "variant" | "events">; // default <TagsInput/> props
  children?: Snippet;
}
type TagsInputFieldReqdProps = never;
type TagsInputFieldBindProps = "values" | "variant" | "element";
```

### Others

No additional exports are available.

## Examples

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

### Basic

**Code**

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

  const styling = {
    label: "font-bold",
    middle: "flex flex-col accent-teal-500",
    bottom: "mt-1 text-xs",
  };
  const myProps = {
    label: "Tags Input Field",
    bottom: "Enter your tags here",
    styling,
  };
  const childStyle = {
    whole: "px-2 py-1 min-w-50 max-w-80 rounded-sm border",
    label: "inline-flex flex-nowrap justify-center items-center gap-1.5 m-1 ps-3 pe-1 rounded-full bg-teal-500",
    extra: "px-1 size-4 fill-white cursor-pointer",
    main: "w-22 outline-hidden",
  };
  const svsTagsInput = {
    placeholder: "Add a tag...",
    maxlength: 6,
    styling: childStyle,
  };
</script>

<TagsInputField {...myProps} tagsInput={svsTagsInput} />
```
### With Interactive Variant

**Code**

```svelte src=TagsInputFieldPract.svelte
<script lang="ts">
  import { TagsInputField, TagsInput } from "svseeds";

  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: "font-bold",
      inactive: "text-red-500",
    },
    middle: "mt-1 flex flex-col accent-teal-500",
    bottom: {
      base: "mt-1 text-xs",
      inactive: "text-red-500",
    },
  };
  const myProps = {
    label: "Favorite Fruits",
    bottom: "Enter your favorites",
    validations: [({ value }: { value: string[] }) => (value.length < 2 ? "At least 2 tags required" : "")],
    constraints: [
      ({ value, values }: { value: string; values: string[] }) =>
        values.length >= 8 ? "Maximum 8 tags allowed" : value.toLowerCase() === "banana" ? "Banana is not allowed" : "",
    ],
    styling,
  };
  const childStyle = {
    whole: "flex flex-col",
    aux: "flex flex-wrap mt-2",
    label: "inline-flex flex-nowrap justify-center items-center gap-1.5 m-1 ps-3 pe-1 rounded-sm bg-teal-500",
    extra: "px-1 size-4 fill-white cursor-pointer",
    main: {
      base: "px-2 w-full max-w-80 border-b outline-hidden",
      ...variantStyle,
    },
  };
  const childProps = {
    side: "right" as const,
    placeholder: "Add a tag...",
    maxlength: 6,
    styling: childStyle,
  };
</script>

<TagsInputField bind:variant {...myProps}>
  <TagsInput {...childProps} />
</TagsInputField>
```