Hig Components Controls

Apple HIG: Selection and Input Controls

Check for .claude/apple-design-context.md before asking questions. Use existing context and only ask for information not already covered.

Key Principles

1. Clear current state. Users must always see what is selected. Toggles show on/off, segmented controls highlight the active segment, pickers display the current selection.

2. Prefer standard system controls. Built-in controls provide consistency and accessibility. Custom controls introduce a learning curve and may break assistive features.

3. Toggles for binary states. On or off. In Settings-style screens, changes take effect immediately. In modal forms, changes commit on confirmation.

4. Segmented controls for mutually exclusive options. 2-5 items, roughly equal importance, short labels.

5. Sliders for continuous values. When precise numeric input is not critical. Provide min/max labels or icons for range endpoints.

6. Pickers for long option lists. Too many options for a segmented control. Works well for dates, times, structured data.

7. Steppers for small, precise adjustments. Increment/decrement in fixed steps. Display current value next to the stepper with reasonable min/max bounds.

8. Text fields for short, single-line input. Text views for multi-line. Configure keyboard type to match expected input (email, URL, number).

9. Combo boxes: text input + selection list. macOS. Type a value or choose from a predefined list when custom values are valid.

10. Token fields: discrete values as visual tokens. macOS. For email recipients, tags, or collections of discrete items.

11. Gauges and rating indicators display values. Gauges show a value within a range. Rating indicators show ratings (often stars). Display-only; use interactive variants for input.

Reference Index

Output Format

1. Control recommendation with rationale and why alternatives are less suitable. 2. State management -- how the control communicates current state and whether changes apply immediately or on confirmation. 3. Validation approach -- when to show errors and how to communicate rules. 4. Accessibility -- labels, traits, hints for VoiceOver.

Questions to Ask

1. What type of data? (Boolean, choice from fixed set, numeric, free-form text?) 2. How many options? 3. Which platforms? (Combo boxes and token fields are macOS-only) 4. Settings screen or inline form?

Related Skills

• hig-components-menus -- Buttons and pop-up buttons complementing selection controls
• hig-components-dialogs -- Sheets and popovers containing forms
• hig-components-search -- Search fields sharing text input patterns
• hig-inputs -- Keyboard, pointer, gesture interactions with controls
• hig-foundations -- Typography, color, layout for control styling

---

Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/combo-boxes.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Combo boxes

Best practices

Populate the field with a meaningful default value from the list.

Use an introductory label to let people know what types of items to expect.

Provide relevant choices.

Make sure list items aren’t wider than the text field.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/combo-boxes

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/controls.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Controls

Anatomy

• In Control Center, a control displays its symbol and, at larger sizes, its title and value.

• On the Lock Screen, a control displays its symbol.

• On iPhone devices with a control assigned to the Action button, pressing and holding it displays the control’s symbol in the Dynamic Island, as well as its value (if present).

Best practices

Offer controls for actions that provide the most benefit without having to launch your app.

Update controls when someone interacts with them, when an action completes, or remotely with a push notification.

Choose a descriptive symbol that suggests the behavior of the control.

Use symbol animations to highlight state changes.

Select a tint color that works with your app’s brand.

Help people provide additional information the system needs to perform an action.

Provide hint text for the Action button.

If your control title or value can vary, include a placeholder.

Hide sensitive information when the device is locked.

Require authentication for actions that affect security.

Camera experiences on a locked device

Use the same camera UI in your app and your camera experience.

Provide instructions for adding the control.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/controls

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/gauges.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Gauges

Best practices

Write succinct labels that describe the current value and both endpoints of the range.

Consider filling the path with a gradient to help communicate the purpose of the gauge.

Platform considerations

macOS

Continuous.

Discrete.

Consider using the continuous style for large ranges.

Consider changing the fill color to inform people about significant parts of the range.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/gauges

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/labels.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Labels

• Within a button, a label generally conveys what the button does, such as Edit, Cancel, or Send.

• Within many lists, a label can describe each item, often accompanied by a symbol or an image.

• Within a view, a label might provide additional context by introducing a control or describing a common action or task that people can perform in the view.

Best practices

Use a label to display a small amount of text that people don’t need to edit.

Prefer system fonts.

Use system-provided label colors to communicate relative importance.

Make useful label text selectable.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/labels

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/pickers.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Pickers

Best practices

Consider using a picker to offer medium-to-long lists of items.

Use predictable and logically ordered values.

Avoid switching views to show a picker.

Consider providing less granularity when specifying minutes in a date picker.

Platform considerations

iOS, iPadOS

• Compact — A button that displays editable date and time content in a modal view.

• Inline — For time only, a button that displays wheels of values; for dates and times, an inline calendar view.

• Wheels — A set of scrolling wheels that also supports data entry through built-in or external keyboards.

• Automatic — A system-determined style based on the current platform and date picker mode.

• Date — Displays months, days of the month, and years.

• Time — Displays hours, minutes, and (optionally) an AM/PM designation.

• Date and time — Displays dates, hours, minutes, and (optionally) an AM/PM designation.

• Countdown timer — Displays hours and minutes, up to a maximum of 23 hours and 59 minutes. This mode isn’t available in the inline or compact styles.

• Compact
• Inline
• Wheels

Use a compact date picker when space is constrained.

macOS

Choose a date picker style that suits your app.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/pickers

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/rating-indicators.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Rating indicators

Best practices

Make it easy to change rankings.

If you replace the star with a custom symbol, make sure that its purpose is clear.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/rating-indicators

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/segmented-controls.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Segmented controls

Best practices

Use a segmented control to provide closely related choices that affect an object, state, or view.

Consider a segmented control when it’s important to group functions together, or to clearly show their selection state.

Keep control types consistent within a single segmented control.

Limit the number of segments in a control.

In general, keep segment size consistent.

Content

Prefer using either text or images — not a mix of both — in a single segmented control.

As much as possible, use content with a similar size in each segment.

Use nouns or noun phrases for segment labels.

Platform considerations

iOS, iPadOS

Consider a segmented control to switch between closely related subviews.

macOS

Consider using introductory text to clarify the purpose of a segmented control.

Use a tab view in the main window area — instead of a segmented control — for view switching.

Consider supporting spring loading.

tvOS

Consider using a split view instead of a segmented control on screens that perform content filtering.

Avoid putting other focusable elements close to segmented controls.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/segmented-controls

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/sliders.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Sliders

Best practices

Customize a slider’s appearance if it adds value.

Use familiar slider directions.

Consider supplementing a slider with a corresponding text field and stepper.

Platform considerations

iOS, iPadOS

Don’t use a slider to adjust audio volume.

macOS

Consider giving live feedback as the value of a slider changes.

Choose a slider style that matches peoples’ expectations.

Consider using a label to introduce a slider.

Use tick marks to increase clarity and accuracy.

Consider adding labels to tick marks for even greater clarity.

visionOS

Prefer horizontal sliders.

watchOS

If necessary, create custom glyphs to communicate what the slider does.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/sliders

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/steppers.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Steppers

Best practices

Make the value that a stepper affects obvious.

Consider pairing a stepper with a text field when large value changes are likely.

Platform considerations

macOS

For large value ranges, consider supporting Shift-click to change the value quickly.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/steppers

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/text-fields.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Text fields

Best practices

Use a text field to request a small amount of information, such as a name or an email address.

Show a hint in a text field to help communicate its purpose.

Use secure text fields to hide private data.

To the extent possible, match the size of a text field to the quantity of anticipated text.

Evenly space multiple text fields.

Ensure that tabbing between multiple fields flows as people expect.

Validate fields when it makes sense.

Use a number formatter to help with numeric data.

Adjust line breaks according to the needs of the field.

Consider using an expansion tooltip to show the full version of clipped or truncated text.

In iOS, iPadOS, tvOS, and visionOS apps, show the appropriate keyboard type.

Minimize text entry in your tvOS and watchOS apps.

Platform considerations

iOS, iPadOS

Display a Clear button in the trailing end of a text field to help people erase their input.

Use images and buttons to provide clarity and functionality in text fields.

macOS

Consider using a combo box if you need to pair text input with a list of choices.

watchOS

Present a text field only when necessary.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/text-fields

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/text-views.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Text views

Best practices

Use a text view when you need to display text that’s long, editable, or in a special format.

Keep text legible.

Make useful text selectable.

Platform considerations

iOS, iPadOS

Show the appropriate keyboard type.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/text-views

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/toggles.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Toggles

Best practices

Use a toggle to help people choose between two opposing values that affect the state of content or a view.

Clearly identify the setting, view, or content the toggle affects.

Make sure the visual differences in a toggle’s state are obvious.

Platform considerations

iOS, iPadOS

Use the switch toggle style only in a list row.

Change the default color of a switch only if necessary.

Outside of a list, use a button that behaves like a toggle, not a switch.

Avoid supplying a label that explains the button’s purpose.

macOS

Use switches, checkboxes, and radio buttons in the window body, not the window frame.

Switches

Prefer a switch for settings that you want to emphasize.

Within a grouped form, consider using a mini switch to control the setting in a single row.

In general, don’t replace a checkbox with a switch.

Checkboxes

Use a checkbox instead of a switch if you need to present a hierarchy of settings.

Consider using radio buttons if you need to present a set of more than two mutually exclusive options.

Consider using a label to introduce a group of checkboxes if their relationship isn’t clear.

Accurately reflect a checkbox’s state in its appearance.

Radio buttons

Prefer a set of radio buttons to present mutually exclusive options.

Avoid listing too many radio buttons in a set.

To present a single setting that can be on or off, prefer a checkbox.

Use consistent spacing when you display radio buttons horizontally.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/toggles

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/token-fields.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Token fields

Best practices

Add value with a context menu.

Consider providing additional ways to convert text into tokens.

Consider customizing the delay the system uses before showing suggested tokens.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/token-fields

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Virtual keyboards

Best practices

Choose a keyboard that matches the type of content people are editing.

• ASCII capable
• ASCII capable number pad
• Decimal pad
• Default
• Email address
• Name phone pad
• Number pad
• Numbers and punctuation
• Phone pad
• Twitter
• URL
• Web search

Consider customizing the Return key type if it helps clarify the text-entry experience.

Custom input views

Make sure your custom input view makes sense in the context of your app.

Play the standard keyboard sound while people type.

Custom keyboards

Provide an obvious and easy way to switch between keyboards.

Avoid duplicating system-provided keyboard features.

Consider providing a keyboard tutorial in your app.

Platform considerations

iOS, iPadOS

Use the keyboard layout guide to make the keyboard feel like an integrated part of your interface.

Place custom controls above the keyboard thoughtfully.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/virtual-keyboards