StyleButton handbook

v1.0.4 · @snowui-design-system/components

License: Before reading component documentation, source, or npm usage instructions for the first time, read the full LICENSE. Reuse that review for the same task and version. Public API configuration and internal implementation changes have different license implications. All components use the unified runtime package; source rights remain governed by the license.

Overview

Switch between SnowUI and Apple visual styles, suitable as an interface style control.

When to use it

Use to switch between supported visual styles. Use ColorSchemeButton for light and dark mode. This button does not permit arbitrary changes to private component styles.

Sync the style through bind:mode; defaultMode supplies the initial mode.
By default the mode is applied to the document. For local control set applyToDocument=false. Without children, the button uses an icon-only layout.

Quick start

This example shows the recommended basic composition. See the sections below for more cases and composition limits.

<script lang="ts">	import { StyleButton } from '@snowui-design-system/components';</script> <StyleButton />

API

Keyword	Type	Default	Description
mode	`SnowUIStyleMode`	—	Current visual style; supports bind:mode. Takes precedence over defaultMode on mount. Clicks update this value, and it follows root attribute changes when document sync is enabled.
defaultMode	`SnowUIStyleMode`	—	Uncontrolled initial value on mount; mode takes precedence. If neither is provided, reads the page root; with applyToDocument=false, falls back to snowui.
applyToDocument	`boolean`	`true`	Syncs current state to document.documentElement: sets mode="ios" or removes mode for SnowUI. When false, the component does not read, write, or observe page attributes; the caller manages the style target. Does not write storage.
ariaLabel	`string`	—	Overrides the accessible button name. The default describes the state a click will switch to and follows LocaleProvider.
snowuiLogo	`Snippet`	`— (built-in graphic)`	Replaces the SnowUI Logo shown in the snowui state. Only the graphic changes; switch logic stays with the component.
appleLogo	`Snippet`	`— (built-in graphic)`	Replaces the Apple Logo shown in the apple state. Only the graphic changes; switch logic stays with the component.
children	`Snippet`	—	Custom content shown after the state graphic. Without it, the host Button uses an iconOnly layout.
disabled	`boolean`	`false`	Disables button interaction but does not stop sync from an external bound value or page attribute.
onModeChange	`(mode: SnowUIStyleMode) => void`	—	Receives the new value after a user click. Initialization, external assignments, and observed page-attribute changes do not call it.
onclick	`(event: MouseEvent) => void`	—	Called before the state switch on a valid click. The current implementation does not let preventDefault() cancel the subsequent switch. Not called when disabled.

See the base component documentation for inherited capabilities not redeclared here. This table lists only named public Props declared by this component.

Usage boundaries and details

Usage

<script lang="ts">  import { StyleButton } from "@snowui-design-system/components";</script> <StyleButton bare />

StyleButton forwards compatible Button Props and supports all variants and sizes. By default it reads document.documentElement: mode="ios" means Apple style and no mode attribute means SnowUI style. The SnowUI state uses SnowUILogo variant="icon"; the Apple state uses the Apple brand logo vector, not an Apple icon from the icon library. Without additional children, StyleButton explicitly sets iconOnly=true on Button, preserving native four-sided Button padding of 4 / 8 / 12px at sm / md / lg.

A click switches immediately. It does not write storage or add an icon-replacement or style-switch transition. With applyToDocument={false}, it maintains only controlled state, suitable when a host such as Test or an iframe manages the actual style target.

This section is protected. An AI must request user review before modifying it.

StyleButton style overrides

Read the full LICENSE first; reuse that review for the same task, version, and scope.

First use public component Props to match the desired appearance, preserving the existing look where possible. If changes are necessary, follow the style selection and override order: use your own class (including Tailwind already in the project) or an instance style. The names below are public overrides actually consumed by source; check their scope and do not modify private DOM. Choose the correct SnowUI token family. External apps need not install SnowUI website utilities.

This component source does not directly consume a registered component-specific override. Style composed children through public parts or an explicit child; do not guess variable names.

Design guide · Tokens · Composition boundaries

StyleButton types and state

Required Props: no named required Props.

Bindable Prop: bind:mode.

Inheritance: Omit< ButtonProps, "children" | "onclick" | "disabled" | "aria-pressed" >. Consult the base class public documentation; fields excluded by Omit cannot be passed through unchanged.

Shared Frame API · Back to API

The following type declarations are actually referenced by public Props and come from source. A Svelte Snippet denotes a content fragment; ComponentProps denotes the Props of the corresponding component.

SnowUIStyleMode

Source: components/src/components/StyleButton.svelte

export type SnowUIStyleMode = "snowui" | "apple";

ButtonProps

Source: components/src/components/StyleButton.svelte

type ButtonProps = ComponentProps<typeof Button>;