Toggle

A two-state button that can be either on or off.

Bold is

Installation

CLI

Install the component using the StarUI CLI:

star add toggle

Examples

Feature Toggles

Enable/disable features with descriptive toggles

Feature Flags

Enable experimental features

Enable beta features

Show debug information

Optimize for speed

Size Variations

Small, default, and large toggle sizes

Small

Default

Large

Social Interactions

Like, comment, save, and share toggles

Beautiful sunset over the mountains

Posted 2 hours ago

from starhtml import *
from starui import *

liked = Signal("liked", False)
comment = Signal("comment", False)
saved = Signal("saved", False)
share = Signal("share", False)

def create_social_toggle(icon, count_signal, sig, label):
    return Toggle(
        Icon(icon, cls="h-4 w-4 mr-1"),
        Span(data_text=count_signal, cls="text-sm"),
        variant="outline",
        signal=sig,
        aria_label=label
    )
Card(
    CardContent(
        Div(
            liked, comment, saved, share,
            Div(
                Icon("lucide:image", cls="h-48 w-full text-muted-foreground/20"),
                cls="bg-muted rounded-md flex items-center justify-center mb-4"
            ),
            P("Beautiful sunset over the mountains", cls="font-medium mb-2"),
            P("Posted 2 hours ago", cls="text-sm text-muted-foreground mb-4"),
            Div(
                create_social_toggle("lucide:heart", liked.if_('124', '123'), liked, "Like post"),
                create_social_toggle("lucide:message-circle", comment.if_('9', '8'), comment, "Comment"),
                Toggle(
                    Icon("lucide:bookmark", cls="h-4 w-4"),
                    variant="outline",
                    signal=saved,
                    aria_label="Save post"
                ),
                Toggle(
                    Icon("lucide:share-2", cls="h-4 w-4"),
                    variant="outline",
                    signal=share,
                    aria_label="Share post"
                ),
                cls="flex gap-2"
            ),
            Div(
                P(
                    Icon("lucide:heart", cls="h-4 w-4 mr-2 text-red-500"),
                    "You liked this",
                    cls="text-xs text-muted-foreground flex items-center",
                    data_show=liked
                ),
                P(
                    Icon("lucide:bookmark", cls="h-4 w-4 mr-2"),
                    "Saved to collection",
                    cls="text-xs text-muted-foreground flex items-center",
                    data_show=saved
                ),
                cls="mt-2 space-y-1 min-h-[32px]"
            )
        )
    ),
    cls="max-w-sm"
)

Music Player Simulation

Simulated music player with realistic timer and toggle controls

Now Playing

Sunset Dreams - Ambient Mix

from starhtml import *
from starui import *

shuffle = Signal("shuffle", False)
playing = Signal("playing", True)
repeat = Signal("repeat", True)
current_time = Signal("current_time", 83)
total_time = Signal("total_time", 296)
song_progress = Signal("song_progress", 28)

Card(
    CardHeader(
        CardTitle("Now Playing"),
        CardDescription("Sunset Dreams - Ambient Mix")
    ),
    CardContent(
        Div(
            shuffle, playing, repeat, current_time, total_time, song_progress,

            Progress(
                signal=song_progress,
                cls="h-2"
            ),

            P(
                data_text=js("Math.floor($current_time / 60) + ':' + String($current_time % 60).padStart(2, '0') + ' / ' + Math.floor($total_time / 60) + ':' + String($total_time % 60).padStart(2, '0')"),
                cls="text-xs text-muted-foreground mt-2 text-center"
            ),

            Div(
                Toggle(
                    Icon("lucide:shuffle", cls="h-4 w-4"),
                    variant="outline",
                    size="sm",
                    signal=shuffle,
                    aria_label="Shuffle"
                ),
                Button(
                    Icon("lucide:skip-back", cls="h-4 w-4"),
                    variant="outline",
                    size="sm",
                    aria_label="Previous Song",
                    data_on_click=[current_time.set(0), song_progress.set(0), playing.set(False)]
                ),
                Toggle(
                    Icon("lucide:play", cls="h-5 w-5", data_show=~playing),
                    Icon("lucide:pause", cls="h-5 w-5", data_show=playing),
                    variant="outline",
                    signal=playing,
                    pressed=True,
                    aria_label="Play/Pause"
                ),
                Button(
                    Icon("lucide:skip-forward", cls="h-4 w-4"),
                    variant="outline",
                    size="sm",
                    aria_label="Next Song",
                    data_on_click=[current_time.set(0), song_progress.set(0), playing.set(False)]
                ),
                Toggle(
                    Icon("lucide:repeat", cls="h-4 w-4"),
                    variant="outline",
                    size="sm",
                    signal=repeat,
                    pressed=True,
                    aria_label="Repeat"
                ),
                cls="flex items-center justify-center gap-2 mt-4"
            ),

            Div(
                Badge(
                    data_text=shuffle.if_("Shuffle ON", "Shuffle OFF"),
                    variant="outline",
                    cls="text-xs"
                ),
                Badge(
                    data_text=repeat.if_("Repeat ON", "Repeat OFF"),
                    variant="outline",
                    cls="text-xs"
                ),
                cls="flex justify-center gap-2 mt-3"
            ),

            data_effect=js("""
                if (window.musicTimer) {
                    clearInterval(window.musicTimer);
                    window.musicTimer = null;
                }

                if ($playing && $current_time < $total_time) {
                    window.musicTimer = setInterval(() => {
                        if (!$playing) {
                            clearInterval(window.musicTimer);
                            return;
                        }

                        if ($current_time < $total_time) {
                            $current_time = $current_time + 1;
                            $song_progress = Math.round(($current_time / $total_time) * 100);
                        } else {
                            clearInterval(window.musicTimer);
                            if ($repeat) {
                                $current_time = 0;
                                $song_progress = 0;
                            } else {
                                $playing = false;
                            }
                        }
                    }, 1000);
                }
            """)
        )
    ),
    cls="max-w-sm"
)

Disabled States

Disabled toggles in different states

Enabled

Disabled

API Reference

Props

Prop	Type	Default	Description
`variant`	`Literal['default','outline']`	`'default'`	Visual style variant
`size`	`Literal['default','sm','lg']`	`'default'`	Button size
`pressed`	`bool`	`False`	Initial pressed state
`signal`	`str`	`auto-generated`	Datastar signal (auto-generated if blank)
`disabled`	`bool`	`False`	Disable the toggle
`aria_label`	`str \| None`	`None`	ARIA label for accessibility
`cls`	`str`	`''`	Additional CSS classes