# CheckField

A form control for selecting options using either checkboxes or radio buttons.

## Usage

Use standalone.

```svelte
<CheckField {...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>
    <span class="label" conditional>
      {label}
      <span class="extra" conditional>{extra}</span>
    </span>
    <span class="aux" conditional>{aux}</span>
  </div>
  <div class="middle">
    {#each options as { value, text }, i}
      <label class="main">
        <input class="left" {...rest} bind:this={elements[i]} />
        <span class="right">{text}</span>
      </label>
    {/each}
  </div>
  <div class="bottom" conditional: has text, or always when reserve>{bottom}</div>
</div>
```

## Props

| Name          | Type                   | Default   | Description                                                               |
| ------------- | ---------------------- | --------- | ------------------------------------------------------------------------- |
| `options*`    | `SvelteMap`            | -         | Display text and corresponding values; empty options prevent rendering    |
| `label`       | `string`               | -         | Field label                                                               |
| `extra`       | `string`               | -         | Extra text shown with the label                                           |
| `aux`         | `Snippet`              | -         | Auxiliary content; receives values, variant, and input elements           |
| `bottom`      | `string`               | -         | Bottom message                                                            |
| `reserve`     | `boolean`              | `false`   | Renders the bottom element even without a message to prevent layout shift |
| `values`      | `string[]`             | -         | Bindable selected values                                                  |
| `multiple`    | `boolean`              | `true`    | Uses checkboxes when true, radios when false                              |
| `validations` | `CheckFieldValidation` | -         | Validation functions for input values                                     |
| `constraints` | `CheckFieldConstraint` | -         | Constraint functions checked on input, separate from validations          |
| `attach`      | `Attachment`           | -         | Svelte attachment on each input                                           |
| `elements`    | `HTMLInputElement[]`   | -         | Bindable input elements                                                   |
| `styling`     | `SVSClass`             | -         | Styling override                                                          |
| `variant`     | `SVSVariant`           | `NEUTRAL` | Bindable variant                                                          |
`*` required. Other `HTMLInputAttributes` are passed to each `<input>` 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, if the value validation succeeds, it switches to `active`; if it fails, it switches to `neutral` temporarily. 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-check-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.
- Option group (`middle`): `role="group"` for multiple checkboxes, or `role="radiogroup"` for single-choice radios, with `aria-labelledby` and `aria-describedby`.
- Validation state: for `multiple={false}`, `aria-invalid` and `aria-errormessage` are applied to the option group; for `multiple={true}`, they are applied to each native input.

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`.

### Standards Basis

CheckField is built on native `<input type="checkbox">` and `<input type="radio">` controls, so keyboard and assistive-technology support follows the browser standard for checkboxes and radios. See the [Concepts standards-first guidance](/docs/concepts) for the library's approach.

## Exports

### Types

```ts
type CheckFieldValidation = SVSFieldValidation<string[]>;
type CheckFieldConstraint = SVSFieldConstraint;
interface CheckFieldProps extends Omit<HTMLInputAttributes, "type" | "value" | "id"> {
  options: SvelteMap<string, string> | Map<string, string>;
  label?: string;
  extra?: string;
  aux?: Snippet<[string[], string, HTMLInputElement[]]>; // Snippet<[values,variant,elements]>
  bottom?: string;
  reserve?: boolean; // (false)
  values?: string[]; // bindable
  multiple?: boolean; // (true)
  validations?: CheckFieldValidation[];
  constraints?: CheckFieldConstraint[];
  attach?: Attachment<HTMLInputElement>;
  elements?: HTMLInputElement[]; // bindable
  styling?: SVSClass;
  variant?: SVSVariant; // bindable (VARIANT.NEUTRAL)
  // class & other HTMLInputAttributes are passed to each <input> via ...rest
}
type CheckFieldReqdProps = "options";
type CheckFieldBindProps = "values" | "variant" | "elements";
```

### Others

No additional exports are available.

## Examples

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

### Basic

**Code**

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

  const styling = {
    label: "font-bold",
    middle: "px-2 flex flex-col accent-teal-500",
    main: "outline-hidden",
    bottom: "mt-1 text-xs",
  };
  const myProps = {
    options: new Map([
      ["1", "option1"],
      ["2", "option2"],
      ["3", "option3"],
    ]),
    label: "Check Field",
    styling,
  };
</script>

<div class="flex flex-col sm:flex-row justify-center items-center gap-10">
  <CheckField values={["1"]} bottom="Select your options" {...myProps} />
  <CheckField multiple={false} bottom="Select your option" {...myProps} />
</div>
```
### With Interactive Variant

**Code**

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

  let { variant = $bindable() } = $props();
  let values = $state([]);
  let form: HTMLFormElement | undefined = $state();
  const variantStyle = {
    neutral: "accent-gray-400",
    active: "accent-teal-500",
    inactive: "accent-red-500",
    blue: "accent-blue-500",
    yellow: "accent-yellow-500",
    sky: "accent-sky-500",
  };
  const styling = {
    label: {
      base: "font-bold",
      inactive: "text-red-500",
    },
    extra: "ps-1 text-gray-400",
    middle: {
      base: "px-2 flex flex-col",
      ...variantStyle,
    },
    main: "outline-hidden",
    bottom: {
      base: "mb-1 text-xs",
      inactive: "text-red-500",
    },
  };
  const myProps = {
    options: new Map([
      ["01", "Apple"],
      ["02", "Orange"],
      ["03", "Banana"],
      ["04", "Grape"],
      ["05", "Peach"],
    ]),
    label: "Favorite Fruits",
    extra: "(optional)",
    bottom: "Choose your favorites",
    validations: [({ value }: { value: string[] }) => (value.length === 1 && value[0] === "03" ? "You can't just pick a banana" : "")],
    styling,
  };
</script>

<form bind:this={form} class="w-50 flex flex-col">
  <CheckField bind:values bind:variant {...myProps} />
  <div class="mt-5">
    <p>values: {values}</p>
  </div>
</form>
```