AisIconCycle
AisIconCycle extends AisIconButton to allow users cycle through multiple states triggered by button clicks. For each state, developers specify an icon, label, and set of styles. AisIconCycle enables toggle controls (e.g. a favorite toggle) or controls to cycle through an enum -- like a sharing status with the values INTERNAL, PUBLIC, and FEATURED.
Sharing status:
Props
v-model
AisIconCycle exposes its internal cycle state through the v-model directive using the standard modelValue prop and the @update:modelValue event. Developers may use v-model to initialize the state and capture state changes. In the example above, notice that the select menu not only follows the value of the icon button as it cycles but that you may also use the select to modify the icon.
states
The states prop expects a JavaScript Map that defines both the set of states to cycle through and the icon definition for each individual state. The states are defined and ordered by the keys in the states map. The keys may be any standard key type -- e.g. string, number, or boolean, which is why we use a Map instead of an Object. Finally, each key maps to an object with the properties icon, label, and styles. These properties are passed to the underlying AisIconButton. The icon attribute may specify either a string for one of our core icons or an imported FontAwesome icon object.
busy
Use the busy prop to indicate that the icon button is busy. When the component is busy, it will not accept additional clicks. This is useful when @click triggers an asynchronous action and must await a response.
Locked: false
AisIconButton props
AisIconCycle accepts all of AisIconButton's props as well. For example, you may set the component's size or enable press effect. See AisIconButton's docs for details. keepFocus is an important prop to consider when the cycle is more than two states. When enabled, it allows the use to use the keyboard to cycle through all the values.
Slots
default slot
AisIconCycle's default slot (i.e. tag body) will populate the default slot of the underlying AisIconButton allowing developers to add descriptive text alongside the icon cycle.
Events
@click
The @click event fires every time the underlying AisIconButton is clicked. The event's payload is an object with the keys newValue, oldValue, and selectedState. The values are keys into the states map, and selectedState is the object mapped to the newValue key. Developers can also embed additional state (e.g. descriptions) in the cycle's map and access that state on the @click event.
Typically, the new value can be transmitted through v-model. However, if an asynchronous action triggered by @click fails, you can use oldValue to reset the state.
Locked: false
@update:modelValue
The @update:modelValue event fires every time the underlying AisIconButton is clicked. The new state will be included as the event's payload. This event is intended for v-model support. @click should be preferred when you need to trigger an action on state change.
Pre-defined States
Ais Components includes several commonly used state definitions. Examples are shown below.
Favorite
Favorite: true
Locked/Unlocked
Locked: false