> Part of the [Tangram component index](/docs/components/index.md). Use the index to find other components.

# Input (Tangram 2)

Put a native `<input>` or `<textarea>` with the `tg2Input` attribute inside `<tg2-input-container>`. Import `Tg2InputContainerComponent` and `Tg2InputDirective`.

- Put form bindings on the native element: `ngModel`, `formControlName` or `formField`.
- Put native attributes on the native element: `type`, `placeholder`, `maxlength`, `readonly`, `autocomplete`.
- The container has no value input or output.

The container sets `aria-invalid`, `aria-required` and `aria-describedby` on the native element.

## Form systems

Every Angular form system works on the projected native element.

```html
<!-- ngModel -->
<tg2-input-container label="Title">
    <input
        tg2Input
        required
        [(ngModel)]="title" />
</tg2-input-container>

<!-- Reactive forms -->
<form [formGroup]="form">
    <tg2-input-container label="Email">
        <input
            tg2Input
            type="email"
            formControlName="email" />
    </tg2-input-container>
</form>

<!-- Signal Forms -->
<tg2-input-container label="Username">
    <input
        tg2Input
        [formField]="userForm.username" />
</tg2-input-container>

<!-- No forms library -->
<tg2-input-container label="Title">
    <input
        tg2Input
        required
        [value]="title"
        (input)="title = $any($event.target).value" />
</tg2-input-container>
```

## The tg2Input directive

The selector is `input[tg2Input], textarea[tg2Input]`.

- `id` sets the id of the native element. If you do not set it, the directive generates an id.
- `aria-describedby` takes the ids of your own elements that describe the field. The directive keeps them and adds the footer id after them.
- Set `aria-describedby="…"` or `[aria-describedby]="…"`. Do not use `[attr.aria-describedby]`, because it overwrites the footer id.

## Label

- `label` is required. `showLabel="false"` hides the label visually. Screen readers still announce it.
- `floatingLabel` puts the label inside the field. The container ignores it when `showLabel` is false.
- "(optional)" shows on the label of every field that is not required.

The container reads required from the native `required` attribute, `Validators.required`, a validator that returns `{ required: true }` for an empty value, or a Signal Forms `required()` rule. Reactive forms do not need `required` on the element as well.

Set `showOptional="false"` to hide "(optional)" on a field that is not a form question, for example a search box.

Angular does not emit an event when validators change. After `setValidators()`, `addValidators()`, `removeValidators()` or `clearValidators()`, call `updateValueAndValidity()`. This updates "(optional)", `aria-required` and the `errors` of the control.

## Footer

The footer shows one message at a time. The order of priority is: error, then characters remaining, then `description`.

## Errors

By default, `errorMessage` shows when the Angular control is touched and invalid.

If your errors come from somewhere else, for example from signals with no validators on the control, set `[error]`:

- `true` shows the error and sets `aria-invalid`.
- `false` hides the error.
- Unset follows the state of the control.

`[error]` also works without a forms library.

```html
<tg2-input-container
    label="First name"
    errorMessage="Enter your first name"
    [error]="firstNameError()">
    <input
        tg2Input
        required
        [ngModel]="firstName()"
        (ngModelChange)="firstName.set($event)" />
</tg2-input-container>
```

## Characters remaining

`showRemainingCharacters` shows a counter. It needs `characterLimit` on the container or a `maxlength` on the native element.

- A native `maxlength` stops the user at the limit.
- `characterLimit` lets the user type past the limit. Over the limit, the counter shows the number of extra characters in the error style.

Over the limit is a warning, not an error. The border, `aria-invalid` and the form validity do not change. To stop the form submission, add your own validation:

- With reactive forms or Signal Forms, add a max length validator and an `errorMessage`. When the field is touched and too long, the error replaces the counter.
- With `ngModel`, use `[error]`. The Angular `maxlength` validator also sets the native attribute, which stops typing.

Screen readers hear the count after the user stops typing, through a hidden live region.

```html
<tg2-input-container
    label="Message"
    characterLimit="500"
    showRemainingCharacters
    errorMessage="Keep your message to 500 characters">
    <textarea
        tg2Input
        [formControl]="message"></textarea>
</tg2-input-container>
```

## Icons and clear button

- `iconLeft` and `iconRight` show a decorative Tangram icon before or after the field.
- `clearable` shows a clear button while the field has a value. The button clears the native value and dispatches an `input` event. It does not submit the form.

## Size and radius

- `size="large"` is 48px, or 56px with a floating label. This is the default.
- `size="medium"` is 38px.
- `radius` is `small` (4px), `medium` (8px) or `large` (16px). Unset, the theme sets it: 8px, or 3px with `theme="tg-light"` or `"tg-dark"`.

<!-- generated:api:start -->
<!-- Generated from tg2-input-container.component.ts by npm run docs:components. Do not edit by hand. -->

## API

Selector: `tg2-input-container`. Import `Tg2InputContainerComponent` from `@trademe/tangram`.

Experimental: the API can change in a minor release.

### Inputs

- `label`: `string`. Required.
- `showLabel`: `boolean`. Default `true`.
- `description`: `string`.
- `errorMessage`: `string`.
- `error`: `boolean`.
- `showOptional`: `boolean`. Default `true`.
- `floatingLabel`: `boolean`. Default `false`.
- `size`: `medium` | `large`. Default `large`.
- `iconLeft`: `TangramIconKind`.
- `iconRight`: `TangramIconKind`.
- `clearable`: `boolean`. Default `false`.
- `showRemainingCharacters`: `boolean`. Default `false`.
- `characterLimit`: `number`.
- `radius`: `small` | `medium` | `large`.
- `theme`: `tg2-light` | `tg2-dark` | `tg-light` | `tg-dark`. Default `tg2-light`.

### Content slots

- `[tg2Input]`

<!-- generated:api:end -->
