Toggle#

The Toggle component in the Scripting app provides a view control that allows users to toggle between "on" and "off" states. It supports various configuration options to suit different use cases, including user interaction handlers, intents for automation, and customization for display purposes.

ToggleProps#

The ToggleProps type defines the configuration options for the Toggle component.

Properties#

value#

• Type: boolean
• Description: Indicates whether the toggle is currently in the "on" (true) or "off" (false) state.
• Required: Yes

onChanged#

• Type: (value: boolean) => void
• Description: A handler function that is invoked whenever the toggle state changes. It receives the new state (true or false) as a parameter.
• Required: Yes, if intent is not provided.

intent#

• Type: AppIntent<any>
• Description: An AppIntent to execute when the toggle is toggled. This is available only for Widget or LiveActivity contexts.
• Required: Yes, if onChanged is not provided.

title#

• Type: string
• Description: A short string describing the purpose of the toggle.
• Optional: Yes, mutually exclusive with children.

systemImage#

• Type: string
• Description: The name of an image resource to display alongside the toggle, typically for enhancing the description.
• Optional: Yes, available only if title is provided.

children#

• Type: (VirtualNode | undefined | null | (VirtualNode | undefined | null)[])[] | VirtualNode
• Description: A custom view that describes the purpose of the toggle, offering a more flexible alternative to title.
• Optional: Yes, mutually exclusive with title.

ToggleStyle#

Defines the appearance and behavior of the Toggle. It can be configured through the toggleStyle property in CommonViewProps.

Options#

• 'automatic': Automatically chooses the most appropriate style based on context.
• 'switch': Displays the toggle as a traditional switch.
• 'button': Displays the toggle as a button.

CommonViewProps#

CommonViewProps provides additional customization options for the Toggle.

Properties#

toggleStyle#

• Type: 'automatic' | 'switch' | 'button'
• Description: Specifies the appearance and behavior of the toggle. Defaults to 'automatic' if not set.
• Optional: Yes

Usage Examples#

Example 1: Basic Toggle with State Change Handler#

1import { Toggle } from 'scripting'
2
3function MyComponent() {
4  const [isEnabled, setIsEnabled] = useState(false)
5
6  return (
7    <Toggle 
8      value={isEnabled} 
9      onChanged={newValue => setIsEnabled(newValue)} 
10      title="Enable Notifications" 
11      systemImage="bell"
12    />
13  )
14}

Example 2: Toggle with AppIntent#

1import { Toggle, } from 'scripting'
2import { SomeToggleIntent } from "./app_intents"
3
4function MyWidget() {
5  const checked = getCheckedState()
6  return (
7    <Toggle 
8        value={checked} 
9        intent={SomeToggleIntent(checked)} 
10        title="Perform Action" 
11        systemImage="action"
12    />
13  )
14}

See Interactive Widget and LiveActivity documentation for more information about AppIntent.#

Example 3: Toggle with Custom View#

1import { Toggle, View } from 'scripting'
2
3function MyComponent() {
4  const [isEnabled, setIsEnabled] = useState(false)
5
6  return (
7    <Toggle 
8      value={isEnabled} 
9      onChanged={newValue => setIsEnabled(newValue)}
10    >
11      <View>
12        <Text>Enable Feature</Text>
13        <Image imageUrl="https://example.com/feature-icon.png" />
14      </View>
15    </Toggle>
16  )
17}

Example 4: Toggle with toggleStyle#

1import { Toggle } from 'scripting'
2
3function StyledToggle() {
4  const [isActive, setIsActive] = useState(false)
5
6  return (
7    <Toggle 
8      value={isActive} 
9      onChanged={newValue => setIsActive(newValue)} 
10      title="Styled Toggle" 
11      toggleStyle="button"
12    />
13  )
14}

This documentation ensures developers can utilize the Toggle component effectively, leveraging its versatility for creating dynamic and interactive UI experiences in the Scripting app.