# @askrjs/ui/toggle

> Published API exports for @askrjs/ui/toggle.

Source: [https://askrjs.com/docs/reference/api/ui/toggle](https://askrjs.com/docs/reference/api/ui/toggle)

Status: stable. Packages: @askrjs/ui/toggle.

**Published packages are authoritative.** Examples may lag behind a published contract. When guidance differs, verify the exports and TypeScript declarations in your installed package, then file an issue.

## Exports

This entrypoint publishes 8 exports from the declarations shipped by @askrjs/ui.

### `PressEvent`

```ts
PressEvent: {
  preventDefault?: () => void;
  stopPropagation?: () => void;
  defaultPrevented?: boolean;
}
```

Press event passed to onPress handler

Compatible with the pressable foundation's PressEvent type.

### `Toggle`

```ts
Toggle: { (props: ToggleButtonProps): JSX.Element; (props: ToggleAsChildProps): JSX.Element; }
```

Headless Toggle component

## Responsibilities
- Compose pressable foundation for interaction behavior
- Apply aria-pressed for toggle state signaling
- Enforce type="button" default to prevent accidental form submission
- Forward props and refs to native button or child element

## Non-Responsibilities (delegated to pressable foundation)
- Keyboard event handling (Enter/Space)
- Pointer event handling
- Disabled state enforcement
- Role attribute application (for non-native elements)

## Invariants
- MUST NOT contain any event handler logic
- MUST NOT check disabled or pressed props directly
- MUST use pressable() for ALL interaction behavior
- MUST use mergeProps() for ALL prop composition
- pressed state is CONTROLLED (consumer manages state)
Renders the `toggle` part of `toggle`.

Supports polymorphic rendering via `asChild`.

````tsx
Native toggle button
```tsx
const pressed = state(false);
<Toggle pressed={pressed()} onPress={() => pressed.set(!pressed())}>
Mute
</Toggle>
```
````

````tsx
Polymorphic rendering (asChild)
```tsx
<Toggle asChild pressed={muted} onPress={toggleMute}>
<span>🔇</span>
</Toggle>
```
````

### `TOGGLE_A11Y_CONTRACT`

```ts
TOGGLE_A11Y_CONTRACT: { readonly ROLE: "button"; readonly KEYBOARD_ACTIVATION: readonly ["Enter", "Space"]; readonly PRESSED_ATTRIBUTE: "aria-pressed"; readonly DISABLED_ATTRIBUTES: { readonly nativeButton: { readonly disabled: true; readonly "aria-disabled": "true"; }; readonly nonNative: { readonly "aria-disabled": "true"; readonly tabIndex: -1; }; }; readonly DATA_ATTRIBUTES: { readonly state: "data-state"; readonly disabled: "data-disabled"; }; readonly FOCUS_RULES: { readonly enabled: "tabIndex >= 0"; readonly disabled: "tabIndex = -1"; readonly visualIndicator: "required"; }; }
```

WAI-ARIA Toggle Button Pattern

Specification: https://www.w3.org/WAI/ARIA/apg/patterns/button/

A toggle button is a two-state button that can be either on or off.
Uses aria-pressed to communicate toggle state to assistive technology.

## Required ARIA
- aria-pressed: 'true' | 'false' (indicates toggle state)
- role: 'button' (when not native button)

## Keyboard Support
- Enter: Activates toggle (on native button and non-button elements)
- Space: Activates toggle

## Focus Management
- Toggle is focusable when not disabled
- Visual focus indicator required

## Disabled State
- aria-disabled when disabled=true
- Removed from tab order
- Visual disabled styling (consumer responsibility)

### `ToggleA11yContract`

```ts
ToggleA11yContract: typeof TOGGLE_A11Y_CONTRACT
```

Type of the Toggle A11y Contract object.

### `ToggleAsChildProps`

```ts
ToggleAsChildProps: ToggleOwnProps & {
  asChild: true;
  children: JSXElement;
  ref?: Ref<Element>;
  type?: never;
}
```

Props when rendering via asChild

- `asChild`: asChild: true;

- `children`: children: JSXElement;

- `disabled`: disabled?: boolean | undefined;

- `onPress`: onPress?: ((e: PressEvent) => void) | undefined;

- `pressed`: pressed?: boolean | undefined;

- `ref`: ref?: Ref<Element>;

- `type`: type?: undefined;

### `ToggleButtonProps`

```ts
ToggleButtonProps: Omit<JSX.IntrinsicElements['button'], 'children' | 'onClick' | 'disabled' | 'type' | 'ref'> & ToggleOwnProps & {
  asChild?: false;
  ref?: Ref<HTMLButtonElement>;
  type?: 'button' | 'submit' | 'reset';
}
```

Props when rendering as a native <button> element

- `asChild`: asChild?: false | undefined;

- `children`: children?: unknown;

- `disabled`: disabled?: boolean | undefined;

- `onPress`: onPress?: ((e: PressEvent) => void) | undefined;

- `pressed`: pressed?: boolean | undefined;

- `ref`: ref?: Ref<HTMLButtonElement>;

- `type`: type?: "button" | "submit" | "reset" | undefined;

### `ToggleOwnProps`

```ts
ToggleOwnProps: {
  children?: unknown;
  onPress?: (e: PressEvent) => void;
  pressed?: boolean;
  disabled?: boolean;
}
```

Props shared by all Toggle variants

- `children`: children?: unknown;

- `disabled`: disabled?: boolean | undefined;

- `onPress`: onPress?: ((e: PressEvent) => void) | undefined;

- `pressed`: pressed?: boolean | undefined;

### `ToggleProps`

```ts
ToggleProps: ToggleButtonProps | ToggleAsChildProps
```

Discriminated union of Toggle prop types

- `asChild`: asChild?: boolean | undefined;

- `children`: children?: unknown;

- `disabled`: disabled?: boolean | undefined;

- `onPress`: onPress?: ((e: PressEvent) => void) | undefined;

- `pressed`: pressed?: boolean | undefined;

- `ref`: ref?: ((value: Element | null) => void) | { current: Element | null; } | ((value: HTMLButtonElement | null) => void) | { current: HTMLButtonElement | null; } | null | undefined;

- `type`: type?: "button" | "submit" | "reset" | undefined;

## Documentation navigation

[Previous](https://askrjs.com/docs/reference/api/ui/textarea/index.md) | [Next](https://askrjs.com/docs/reference/api/ui/toggle-group/index.md)