Toggle component

Learn about how to configure the toggle switch component.

Basic usage

Minimal configuration

At minimum, the toggle component requires the following configuration to function:

val toggleConfig = ToggleComponentConfig(
    label = "Use different PayPal account"
)

Property	Description
`label` String required	The toggle label text. This is displayed next to the switch and describes the toggle's purpose.

Advanced configuration

For more complex implementations, you can configure additional settings:

val toggleConfig = ToggleComponentConfig(
    // Required configuration
    label = "Use different PayPal account",
    
    // Initial state
    initialChecked = false,
    
    // Indicators
    activeIndicator = "ON",
    inactiveIndicator = "OFF",
    
    // Visibility
    isVisible = true
)

Property	Description
`initialChecked` Boolean	The initial toggle state. Defaults to `false`.
`activeIndicator` String?	Optional text displayed on the active toggle. Requires `toggleStyle.showIndicator = true`. Defaults to `null`.
`inactiveIndicator` String?	Optional text displayed on the inactive toggle. Requires `toggleStyle.showIndicator = true`. Defaults to `null`.
`isVisible` Boolean	Whether the toggle is visible. Defaults to `true`.

The toggle uses Android's Material Switch composable under the hood, ensuring native platform behaviour while allowing extensive customisation.

Styling

Default styling

The toggle component renders with these default styles:

labelStyle = ToggleLabelStyle(
    color = Color.Black,
    fontSizeSp = 16f,
    fontWeight = FontWeight.Normal,
    position = LabelPosition.END,
    spacing = 8.dp
)

toggleStyle = ToggleVisualStyle(
    width = 48.dp,
    height = 28.dp,
    borderRadius = 14.dp,
    activeTrackColor = Color(0xFF0B74C8),
    inactiveTrackColor = Color(0xFFB0BEC5),
    activeThumbColor = Color.White,
    inactiveThumbColor = Color.White
)

Custom styling

You can override the default appearance by providing custom styles for any part of the component:

val toggleConfig = ToggleComponentConfig(
    label = "Use different PayPal account",
    
    // Label styling
labelStyle = ToggleLabelStyle(
        color = Color(0xFF2C2E2F),
        fontSizeSp = 15f,
        fontWeight = FontWeight.Medium,
        position = LabelPosition.START,
        spacing = 12.dp
    ),
    
    // Toggle switch styling
toggleStyle = ToggleVisualStyle(
        // Dimensions
        width = 54.dp,
        height = 32.dp,
        borderWidth = 2.dp,
        borderColor = Color(0xFFDEE2E6),
        borderRadius = 16.dp,
        
        // Colors
        activeTrackColor = Color(0xFF0070BA),
        inactiveTrackColor = Color(0xFFCED4DA),
        activeThumbColor = Color.White,
        inactiveThumbColor = Color.White,
        
        // Indicators
        showIndicator = true,
        indicatorTextSizeSp = 10f,
        indicatorFontWeight = FontWeight.Bold,
        indicatorTextColor = Color.White
    ),
    
    activeIndicator = "ON",
    inactiveIndicator = "OFF"
)

Property	Description
`labelStyle` ToggleLabelStyle	Label typography and positioning controls. Defaults to the default label style.
`labelStyle.color` Color	The text colour of the label. Defaults to `Color.Black`.
`labelStyle.fontSizeSp` Float	The font size in scaled pixels. Defaults to `16f`.
`labelStyle.fontWeight` FontWeight	The weight/boldness of the text. Defaults to `FontWeight.Normal`.
`labelStyle.position` LabelPosition	The label position relative to toggle. Defaults to `LabelPosition.END`. Possible values: `START`: Left of the toggle `END`: Right of the toggle `TOP`: Above the toggle `BOTTOM`: Below the toggle
`labelStyle.spacing` Dp	The distance between the label and toggle. Defaults to `8.dp`.
`toggleStyle` ToggleVisualStyle	Switch appearance controls. Defaults to the default toggle style.
`toggleStyle.width` Dp	The width of the toggle track. Defaults to `48.dp`.
`toggleStyle.height` Dp	The height of the toggle track. Defaults to `28.dp`.
`toggleStyle.borderWidth` Dp	The border thickness around the toggle. Defaults to `0.dp`.
`toggleStyle.borderColor` Color	The colour of the border. Defaults to transparent.
`toggleStyle.borderRadius` Dp	The corner radius of the toggle. Defaults to `14.dp`.
`toggleStyle.activeTrackColor` Color	The track colour when the toggle is on. Defaults to `Color(0xFF0B74C8)`.
`toggleStyle.inactiveTrackColor` Color	The track colour when the toggle is off. Defaults to `Color(0xFFB0BEC5)`.
`toggleStyle.activeThumbColor` Color	The thumb (circle) colour when on. Defaults to `Color.White`.
`toggleStyle.inactiveThumbColor` Color	The thumb (circle) colour when off. Defaults to `Color.White`.
`toggleStyle.showIndicator` Boolean	Whether to show text indicators on the toggle track. Defaults to `false`.
`toggleStyle.indicatorTextSizeSp` Float	The font size for the indicator text. Defaults to `10f`.
`toggleStyle.indicatorFontWeight` FontWeight	The font weight for the indicator text. Defaults to `FontWeight.Normal`.
`toggleStyle.indicatorTextColor` Color	The colour of the indicator text. Defaults to `Color.White`.

Event handling

The toggle component provides event handlers for user interactions:

val toggleConfig = ToggleComponentConfig(
    onToggleChanged = { isChecked: Boolean -> }
)

Callback	Description
`onToggleChanged: ((Boolean) -> Unit)?`	Event handler for when the toggle's state changes. The boolean parameter indicates the new checked state (`true` for on, `false` for off).

For detailed information about event data structures and usage patterns, see Events.

Methods

The toggle component provides methods for state management.

Content()

Renders the toggle switch in Jetpack Compose:

@Composable
fun ToggleSection() {
    val toggleComponent = remember {
        pxpCheckout.createComponent(
            type = ComponentType.TOGGLE,
            config = toggleConfig
        )
    }
    
    pxpCheckout.buildComponentView(
        component = toggleComponent,
        modifier = Modifier.fillMaxWidth()
    )
}

getValue()

Retrieves the current toggle state:

val isToggleOn = toggleComponent.getValue() as? Boolean ?: false

setVisibility()

Controls the visibility of the toggle:

toggleComponent.setVisibility(isVisible = true)

Examples

Basic toggle switch

A straightforward implementation with essential configuration:

val toggleConfig = ToggleComponentConfig(
    label = "Use different PayPal account",
    initialChecked = false,
    
    onToggleChanged = { isChecked ->
        Log.d("Toggle", "Payment method toggle: $isChecked")
        if (isChecked) {
            showPayPalLogin()
        } else {
            useVaultedAccount()
        }
    }
)

Toggle with indicators

Implementation with visual on/off indicators:

val toggleConfig = ToggleComponentConfig(
    label = "Enable one-click payment",
    initialChecked = false,
    activeIndicator = "ON",
    inactiveIndicator = "OFF",
    
    toggleStyle = ToggleVisualStyle(
        width = 54.dp,
        height = 32.dp,
        borderRadius = 16.dp,
        activeTrackColor = Color(0xFF28A745),
        inactiveTrackColor = Color(0xFFDC3545),
        activeThumbColor = Color.White,
        inactiveThumbColor = Color.White,
        showIndicator = true,
        indicatorTextSizeSp = 10f,
        indicatorFontWeight = FontWeight.Bold,
        indicatorTextColor = Color.White
    ),
    
    onToggleChanged = { isChecked ->
        Log.d("Toggle", "One-click payment: ${if (isChecked) "enabled" else "disabled"}")
        updateOneClickPaymentPreference(isChecked)
    }
)

Enterprise toggle with custom styling

A comprehensive implementation with full customisation:

val toggleConfig = ToggleComponentConfig(
    label = "Change preferred payment method",
    initialChecked = false,
    activeIndicator = "YES",
    inactiveIndicator = "NO",
    
    // Custom label styling
    labelStyle = ToggleLabelStyle(
        color = Color(0xFF212529),
        fontSizeSp = 15f,
        fontWeight = FontWeight.SemiBold,
        position = LabelPosition.START,
        spacing = 16.dp
    ),
    
    // Custom toggle styling
    toggleStyle = ToggleVisualStyle(
        // Dimensions
        width = 60.dp,
        height = 34.dp,
        borderWidth = 2.dp,
        borderColor = Color(0xFFDEE2E6),
        borderRadius = 17.dp,
        
        // Active state colors
        activeTrackColor = Color(0xFF0070BA),
        activeThumbColor = Color.White,
        
        // Inactive state colors
        inactiveTrackColor = Color(0xFFE9ECEF),
        inactiveThumbColor = Color(0xFF6C757D),
        
        // Indicator styling
        showIndicator = true,
        indicatorTextSizeSp = 9f,
        indicatorFontWeight = FontWeight.Black,
        indicatorTextColor = Color.White
    ),
    
    onToggleChanged = { isChecked ->
        Log.d("Toggle", "Payment method switch toggled: $isChecked")
        
        // Track analytics
        trackAnalyticsEvent("payment_method_toggle", mapOf(
            "action" to if (isChecked) "change_method" else "use_saved",
            "timestamp" to System.currentTimeMillis()
        ))
        
        // Update UI state
        if (isChecked) {
            // User wants to use a different payment method
            showPaymentMethodSelector()
            hideVaultedPaymentInfo()
        } else {
            // User wants to use saved payment method
            hidePaymentMethodSelector()
            showVaultedPaymentInfo()
        }
        
        // Save preference
        savePaymentMethodPreference(isChecked)
    }
)

Linked with PayPal component

Example showing how to link toggle with PayPal component:

// Create toggle component first
val toggleComponent = pxpCheckout.createComponent(
    type = ComponentType.TOGGLE,
    config = ToggleComponentConfig(
        label = "Use different PayPal account",
        initialChecked = false,
        labelStyle = ToggleLabelStyle(
            color = Color(0xFF0070BA),
            fontSizeSp = 14f,
            fontWeight = FontWeight.Medium,
            position = LabelPosition.END,
            spacing = 12.dp
        ),
        toggleStyle = ToggleVisualStyle(
            activeTrackColor = Color(0xFF0070BA),
            inactiveTrackColor = Color(0xFFCED4DA)
        )
    )
)

// Link to PayPal component
val paypalConfig = PayPalComponentConfig(
    renderType = "standalone",
    fundingSources = "paypal",
    enableOneClickPayment = true,
    toggleComponent = toggleComponent,
    scriptParams = PayPalScriptParams(
        userIdToken = getUserIdToken()
    )
)

Dynamic toggle visibility

Example showing how to control toggle visibility based on vault status:

@Composable
fun DynamicPayPalToggle() {
    var hasVaultedAccount by remember { mutableStateOf(false) }
    
    LaunchedEffect(Unit) {
        hasVaultedAccount = checkVaultStatus()
    }
    
    val toggleConfig = remember {
        ToggleComponentConfig(
            label = "Change payment method",
            initialChecked = false,
            isVisible = hasVaultedAccount,
            onToggleChanged = { isChecked ->
                handlePaymentMethodChange(isChecked)
            }
        )
    }
    
    val toggleComponent = remember {
        pxpCheckout.createComponent(
            type = ComponentType.TOGGLE,
            config = toggleConfig
        )
    }
    
    // Toggle automatically shows/hides based on vault status
    if (hasVaultedAccount) {
        pxpCheckout.buildComponentView(
            component = toggleComponent,
            modifier = Modifier.fillMaxWidth()
        )
    }
}