# Form field

- Entry point: `@koobiq/components/form-field`
- NgModule: `KbqFormFieldModule`
- API: https://koobiq.io/api/form-field.md
- Component tokens: https://koobiq.io/tokens/form-field.md
- Page: https://koobiq.io/en/components/form-field/overview

`<kbq-form-field>` is a component used to create forms and input fields with support for styling and additional features.

[**Example: Form field** (`form-field-overview`)](https://koobiq.io/examples/form-field-overview.md)

The following components are intended to work inside the `<kbq-form-field>` component:

- [Autocomplete](https://koobiq.io/en/components/autocomplete.md)
- [Input](https://koobiq.io/en/components/input.md)
- [Select](https://koobiq.io/en/components/select.md)
- [Tag autocomplete](https://koobiq.io/en/components/tag-autocomplete.md)
- [Tag input](https://koobiq.io/en/components/tag-input.md)
- [Textarea](https://koobiq.io/en/components/textarea.md)
- [Timepicker](https://koobiq.io/en/components/timepicker.md)
- [Timezone](https://koobiq.io/en/components/timezone.md)
- [Tree select](https://koobiq.io/en/components/tree-select.md)

## Label

`<kbq-label>` names the field. The `showRequiredMarker` attribute ends the label
of a required field with the `*` marker: a field is required when it has the `required` attribute or the
`Validators.required` validator. The marker is hidden by default; the [global options](#global-options) turn it on for every field.

[**Example: Form field with kbq-label** (`form-field-with-label`)](https://koobiq.io/examples/form-field-with-label.md)

## Horizontal form

To create a horizontal form, add the `horizontal` attribute to the `<kbq-form-field>` component.

[**Example: Form field horizontal** (`form-field-horizontal`)](https://koobiq.io/examples/form-field-horizontal.md)

## Hints

`<kbq-hint>` is a component used to add hints to form fields inside the `<kbq-form-field>` component.
Hints can be useful for providing additional information on how to fill out the field, what data is expected,
or for displaying additional instructions.

[**Example: Form field with kbq-hint** (`form-field-with-hint`)](https://koobiq.io/examples/form-field-with-hint.md)

## Error messages

`<kbq-error>` is a component used to display validation error messages for form fields inside the `<kbq-form-field>` component. Errors are initially **hidden** and will be displayed **only** for invalid form fields after user interaction or form submission.

[**Example: Form field with kbq-error** (`form-field-with-error`)](https://koobiq.io/examples/form-field-with-error.md)

## Changing error message display behavior

By default, error highlighting and messages are displayed for **invalid** fields after user interaction (touched or form submitted) with the form element. This behavior can be overridden using [ErrorStateMatcher](https://github.com/koobiq/angular-components/blob/main/packages/components/core/error/error-state-matcher.ts), which provides the ability to flexibly configure the logic for highlighting and displaying validation errors, allowing you to adapt the behavior of input fields to the specific requirements of the application.

You can use one of the built-in `ErrorStateMatcher`, or write your own implementation:

```ts
/**
 * Highlights and displays an error for an invalid field after form submission
 * Copy of ShowOnFormSubmitErrorStateMatcher: https://github.com/koobiq/angular-components/blob/main/packages/components/core/error/error-state-matcher.ts
 */
class CustomErrorStateMatcher implements ErrorStateMatcher {
    isErrorState(control: AbstractControl | null, form: FormGroupDirective | NgForm | null): boolean {
        return !!(control?.invalid && form?.submitted);
    }
}
```

Override

For a specific field, using the `errorStateMatcher` attribute:

[**Example: Form field with CustomErrorStateMatcher which set by \`errorStateMatcher\` attribute** (`form-field-with-custom-error-state-matcher-set-by-attribute`)](https://koobiq.io/examples/form-field-with-custom-error-state-matcher-set-by-attribute.md)

For all fields, using the `ErrorStateMatcher` token:

[**Example: Form field with CustomErrorStateMatcher which set by DI provider** (`form-field-with-custom-error-state-matcher-set-by-dependency-injection-provider`)](https://koobiq.io/examples/form-field-with-custom-error-state-matcher-set-by-dependency-injection-provider.md)

For a full explanation of both approaches, built-in matchers, and component-specific patterns (tag list, file upload), see the [Validation](https://koobiq.io/en/other/validation.md) guide.

## Field cleaning

`<kbq-cleaner />` is a component that adds a clear button for **filled** form fields inside the `<kbq-form-field>` component.

[**Example: Form field with kbq-cleaner** (`form-field-with-cleaner`)](https://koobiq.io/examples/form-field-with-cleaner.md)

## Prefix and suffix

`kbqPrefix` and `kbqSuffix` are directives that allow adding custom elements **before** and **after** the form field inside the `<kbq-form-field>` component. These directives are useful for adding icons, text, buttons, and other elements that should be placed next to the form field.

[**Example: Form field with kbqPrefix and kbqSuffix** (`form-field-with-prefix-and-suffix`)](https://koobiq.io/examples/form-field-with-prefix-and-suffix.md)

## Focus

In text input fields, a blue border is always displayed when focused, regardless of the activation method (mouse, keyboard, or touch).
For form elements with dropdown lists (such as: [select](https://koobiq.io/en/components/select.md), [timezone](https://koobiq.io/en/components/timezone.md), and [tree select](https://koobiq.io/en/components/tree-select.md)),
the focus border is shown only during keyboard navigation (using the `Tab` key) and is hidden when the dropdown list is opened.

## Disabling borders

For a specific field, using the `noBorders` attribute:

[**Example: Form field without borders** (`form-field-without-borders`)](https://koobiq.io/examples/form-field-without-borders.md)

For all fields, in the [global options](#global-options).

## Autofill

To change the tint or switch it off, override the token on the field:

```css
.my-form-field {
    /* look exactly like a normally filled field */
    --kbq-form-field-states-autofill-background: transparent;
}
```

The state is also tracked in TypeScript. `KbqInput`, `KbqInputPassword`, `KbqTextarea` and `KbqTagInput` (forwarded by `KbqTagList`) each wrap the CDK's `AutofillMonitor` around their own element and expose the result as an `autofilled` signal, which `<kbq-form-field>` reflects as the `kbq-form-field_autofilled` class:

```ts
readonly input = viewChild.required(KbqInput);

// ...

const filledByBrowser = this.input().autofilled();
```

The signal is a hook for application code, not the mechanism behind the styling: it arrives a frame or two after the browser paints, where the CSS matches in the same style pass.

## Password input field

`<kbq-password-toggle>` is a component that adds a _"Show password"_ button for **filled** `<input kbqInputPassword />` fields inside the `<kbq-form-field>` component.

`<kbq-reactive-password-hint>` is a component used to add hints to the `<input kbqInputPassword />` field inside the `<kbq-form-field>` component. The `[hasError]` input sets the state of the hint: bind it to the error of the matching validator of the form control.

The example uses [PasswordValidators](https://github.com/koobiq/angular-components/blob/main/packages/components/core/forms/validators.ts) - a set of static methods for password validation.

[**Example: Form field password overview** (`form-field-password-overview`)](https://koobiq.io/examples/form-field-password-overview.md)

## Troubleshooting

### Error: kbq-form-field must contain a KbqFormFieldControl

This error occurs when `<kbq-form-field>` does not contain a form field, such as `<input kbqInput />` or its import `KbqInputModule`.

### Error: You should use kbq-password-toggle with kbqInputPassword

This error occurs when `<kbq-password-toggle>` cannot find the `<input kbqInputPassword />` field or its import `KbqInputModule`.

### Error: You should use kbq-stepper with kbqNumberInput

This error occurs when `<kbq-stepper>` cannot find the `<input kbqNumberInput />` field or its import `KbqInputModule`.

## Global options

The `kbqFormFieldDefaultOptionsProvider` function sets the default options of every field in the application or in a specific injector.

```ts
import { ApplicationConfig } from '@angular/core';
import { kbqFormFieldDefaultOptionsProvider } from '@koobiq/components/form-field';

export const appConfig: ApplicationConfig = {
    providers: [kbqFormFieldDefaultOptionsProvider({ showRequiredMarker: true, noBorders: true })]
};
```
