Forms

Stable - @kikita-labs/ui v2.0.0

Input

Input keeps the control native and applies Kikita UI styling through the kuiInput directive.

Import

Import the public input primitives from the package entrypoint.

input.ts
import {
  KuiField,
  KuiFieldAffix,
  KuiInput,
} from '@kikita-labs/ui';

Usage

Open in Playground

Use kuiInput on native input elements. Use Field only when the control needs label, hint, or error chrome.

<div class="basic-input-example">
  <input kuiInput type="email" aria-label="Work email" placeholder="mira@company.dev" />
  <input kuiInput aria-label="Project slug" value="kikita-ui" />
  <input kuiInput invalid aria-label="Invalid project slug" value="Invalid value" />
</div>

Input group

Drop kuiFieldAffix inside kui-field for prefix text, suffix text, icons, or trailing actions. It auto-detects its look from the host element (button, kui-icon, or plain text) and kui-field applies shared .kui-input-group chrome automatically — no wrapper div needed.

https://.dev

Affixes are visual field chrome.

<kui-field label="Project URL" hint="Affixes are visual field chrome." class="input-group-example">
  <span kuiFieldAffix>https://</span>
  <input kuiInput aria-label="Project slug" value="kikita-ui" />
  <span kuiFieldAffix>.dev</span>
</kui-field>

Forms

Put [formField] on the same native input as kuiInput. Signal Forms owns the value, required, disabled, touched and validation state; kuiInput adds no constraint or rule.

profile-form.html
<kui-field label="Email" hint="Use your work email">
  <input kuiInput type="email" autocomplete="email" [formField]="profileForm.email" />
</kui-field>

Signal Forms supplies raw validity through the native control invalid property. The Field gates the displayed state on touch, so with [formField] the input follows the Field state instead of treating a raw invalid binding as a manual override.

Provider defaults

Set defaults.input once for the application or for a subtree. Each option resolves as local input > defaults.input.<option> > built-in default.

import { provideKikitaUi } from '@kikita-labs/ui';

export const appConfig: ApplicationConfig = {
  providers: [
    provideKikitaUi({
      defaults: {
        input: {
          /* options below */
        },
      },
    }),
  ],
};
NameTypeDefaultDescription
size'xs' | 'sm' | 'md' | 'lg' — Component size. Takes precedence over the global defaults.size.

Theming tokens

Set any of these on the component or an ancestor to restyle one part. Each token is optional: when it is not set, the part uses the role or scale token in the default column.

NameTypeDefaultDescription
--kui-input-font-sizeCSS custom property--kui-text-sm-sizeFont size
--kui-input-height-xsCSS custom property--kui-control-height-xsHeight, xs
--kui-input-font-size-xsCSS custom property--kui-text-xs-sizeFont size, xs
--kui-input-height-smCSS custom property--kui-control-height-smHeight, sm
--kui-input-height-lgCSS custom property--kui-control-height-lgHeight, lg
--kui-input-font-size-lgCSS custom property--kui-text-base-sizeFont size, lg

API

Inputs verified against @kikita-labs/ui v2.0.0 public typings.

NameTypeDefaultDescription
size'xs' | 'sm' | 'md' | 'lg' | undefinedundefinedResolved in order: local size, parent Field effective size, defaults.input.size, root defaults.size, then md. The resolved value is written to data-kui-size.
invalidbooleanfalseMarks a standalone input (or one outside a Field error state) invalid: sets data-kui-invalid and aria-invalid="true". With [formField] the Field state wins and this binding is not a manual override.
idstring | undefinedundefinedInside a Field, omitted uses the Field generated control id; outside, no id is added. An explicit id can leave the Field label for attribute pointing elsewhere.
KuiInputOptionsinterface-Shape of defaults.input: size.

Accessibility

Keep native input semantics. Add labels through Field or native label elements.

  • Keep the native input semantics; do not add an ARIA role.
  • Give every input an accessible name through a kui-field label, a native label or aria-label. A placeholder alone is not a label.
  • Inside a Field the input uses the generated control id and references only the rendered hint and error through aria-describedby; a visible error is role="alert".
  • aria-invalid is omitted while valid; when invalid the directive sets aria-invalid="true" and data-kui-invalid.
  • Keep disabled and readonly distinct: a read-only input stays focusable. Required semantics come from native HTML or Signal Forms, not the Field marker.
  • Decorative affix icons use aria-hidden="true".
  • Interactive field actions must be native buttons with accessible names.
  • kuiInput adds no keyboard handlers: Tab focus, editing and type-specific keys stay native.

Migrating to 2.0

Consumer-visible changes of @kikita-labs/ui 2.0 for Input.

  • The directive class is KuiInput; the Directive suffix is gone.
  • The default size moved to provideKuiDefaults({ input: { size } }); the old provideKikitaUi({ input }) shape is deprecated.
  • Input height and font size per size now have geometry tokens (--kui-input-height-*, --kui-input-font-size-*).
  • A Field size only styles descendant inputs without data-kui-size, so an input with an explicit size keeps it inside a differently sized Field.
  • With [formField], kuiInput follows the Field's touch-gated invalid state.