Forms

Stable - @kikita-labs/ui v2.0.0

Segmented

Compact single-choice control for switching related views or modes.

Import

Segmented composes a container component with projected native buttons marked by kuiSegment.

segmented.ts
import { KuiSegment, KuiSegmented } from '@kikita-labs/ui';

Usage

Open in Playground

Bind the selected segment with a signal and keep each projected button native.

Selected view: list

<div class="basic-segmented-example">
  <kui-segmented [(value)]="view" aria-label="Project view">
    <button kuiSegment value="list">List</button>
    <button kuiSegment value="board">Board</button>
    <button kuiSegment value="timeline">Timeline</button>
  </kui-segmented>

  <p>Selected view: {{ view() }}</p>
</div>

Provider defaults

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

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

export const appConfig: ApplicationConfig = {
  providers: [
    provideKikitaUi({
      defaults: {
        segmented: {
          /* 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-seg-focus-ring-colorCSS custom property--kui-color-focusFocus ring color

API

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

NameTypeDefaultDescription
[(value)]string''Selected segment value. Implements FormValueControl for [formField] integration, or bind directly for standalone use.
[(selected)]string''Deprecated alias for value, kept in sync with it. Use value instead; planned for removal in the next major version.
size'xs' | 'sm' | 'md' | 'lg' | undefinedundefinedControl height and spacing for the whole segmented group. Falls back to defaults.segmented.size, then the global defaults.size, then md.
disabledbooleanfalseDisables every segment. Set by [formField] or directly.
invalidbooleanfalseMarks the control as having validation errors. Set by [formField].
errorsreadonly WithOptionalFieldTree<ValidationError>[][]Current validation errors. Set by [formField].
touchedbooleanfalseWhether the control has been touched. Set by [formField].
(touch)void-Emitted whenever an enabled segment is selected, including one that was already selected; marks the control as touched in the form system. Focus and blur alone do not emit it.
button[kuiSegment].valuestring''Value emitted when the segment is selected.
button[kuiSegment].disabledbooleanfalseDisables one segment and removes it from keyboard selection.
focus(options?)(options?: FocusOptions) => void-Focuses the selected segment, or the first enabled one when nothing is selected, so Signal Forms focusBoundControl() reaches the control. Does nothing while every segment is disabled.
required--Not available: a segmented control always shows one active segment, so it exposes no required state.
KuiSegmentedOptionsinterface-Shape of defaults.segmented: size.

Version notes

Changes introduced in @kikita-labs/ui v1.5.0 that affect existing markup.

  • Segmented now implements FormValueControl<string> and accepts [formField] directly on kui-segmented for Signal Forms integration.
  • The selected/selectedChange model is deprecated in favor of value/valueChange. Existing [(selected)] bindings keep working and stay in sync with value, but are planned for removal in the next major version. New markup should use [(value)].

Accessibility

Segmented uses radiogroup semantics while preserving native button focus.

  • The container renders role="radiogroup".
  • ArrowLeft, ArrowRight, ArrowUp and ArrowDown move focus between segments; Home and End focus the first and last; Enter and Space select the focused segment.
  • Each segment button renders role="radio" and selection state.
  • Disabled segments cannot be selected.
  • focus() lands on the selected segment, so Signal Forms focusBoundControl() reaches the control instead of the group host.
  • Use an accessible label on the segmented group when nearby text is not enough.

Migrating to 2.0

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

  • The classes are KuiSegmented and KuiSegment; the Component and Directive suffixes are gone.
  • The default size moved to provideKuiDefaults({ segmented: { size } }); the input is now undefined until set.
  • kui-segmented gains focus(options?), so Signal Forms focusBoundControl() reaches the selected segment.
  • ArrowUp and ArrowDown now also move focus between segments.
  • The focus ring has --kui-seg-focus-ring-color, and disabled segments use the shared --kui-opacity-disabled.