# Titanium.UI.Switch > An on/off switch control. - Source: https://titaniumsdk.com/docs/sdk/main/Titanium.UI.Switch - Titanium SDK version: main - Kind: view - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 0.8 - Extends: Titanium.UI.View - Inheritance: Titanium.UI.View > Titanium.Proxy | Android | iOS | | ------- | --- | | ![Android](./switch_android.png) | ![iOS](./switch_ios.png) | The appearance of a `Switch` control varies by platform: * On Android, a Switch object can be styled either as a switch, checkbox or toggle button based on the [Titanium.UI.Switch.style](https://titaniumsdk.com/docs/sdk/Titanium.UI.Switch.md#style) property. The checkbox style can optionally display a label next to the control. * On iOS, a Switch appears as an iOS on/off switch and doesn't have any text associated with it. Use the [Titanium.UI.createSwitch](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#createSwitch) method or **``** Alloy element to create a switch. ## Example: Simple Switch Example Create a standard switch, using default values, and output value property on each `change` event. ``` js var win = Ti.UI.createWindow({ backgroundColor: 'white' }); var basicSwitch = Ti.UI.createSwitch({ value:true // mandatory property for iOS }); win.add(basicSwitch); basicSwitch.addEventListener('change',function(e){ Ti.API.info('Switch value: ' + basicSwitch.value); }); win.open(); // print initial value Ti.API.info('Switch value: ' + basicSwitch.value); ``` ## Example: Toggle Button Switch Example (Android) Create a standard (toggle button) switch with a customized title for each on/off state, and output value property on each `change` event. ``` js var win = Ti.UI.createWindow({ backgroundColor: 'white' }); var basicSwitch = Ti.UI.createSwitch({ style: Ti.UI.SWITCH_STYLE_TOGGLE_BUTTON, titleOn:'Notifications Enabled', titleOff:'Notifications Disabled', value:true, width: 200, height:120 }); win.add(basicSwitch); basicSwitch.addEventListener('change',function(e){ Ti.API.info('Switch value: ' + basicSwitch.value); }); win.open(); ``` ## Example: Checkbox Switch Example (Android) Create a checkbox switch, and output value property on each `change` event. ``` js var win = Ti.UI.createWindow({ backgroundColor: 'white' }); var basicSwitch = Ti.UI.createSwitch({ style: Ti.UI.SWITCH_STYLE_CHECKBOX, textAlign:Ti.UI.TEXT_ALIGNMENT_CENTER, title:'Notifications', value:true, width: 300 // necessary for textAlign to be effective }); win.add(basicSwitch); basicSwitch.addEventListener('change',function(e){ Ti.API.info('Switch value: ' + basicSwitch.value); }); win.open(); ``` ## Example: Alloy XML Markup Previous simple switch example as an Alloy view. switchexample.xml: ``` xml ``` switchexample.js: ``` js function outputState(){ Ti.API.info('Switch value: ' + $.basicSwitch.value); } ``` ## Properties ### animated - Type: Boolean - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 5.1.1 - Default: `undefined (equivalent to true)` Determines if there is animation when the switch value changes. Set to `true` if animation is desired or `false` for no animation. ### color - Type: String | Titanium.UI.Color - Platforms: Android - Default: `black` Color to use for switch text, as a color name or hex triplet. For information about color values, see the "Colors" section of [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md). ### enabled - Type: Boolean - Platforms: Android, iPhone, iPad, macOS - Default: `undefined (equivalent to enabled)` Determines whether the switch is enabled. Be careful not to confused this with the [value](https://titaniumsdk.com/docs/sdk/Titanium.UI.Switch.md#value) property, which is used to turn the switch on and off. Set to `true` to enable or `false` to disable the switch. ### font - Type: Font - Platforms: Android Font to use for the switch text. ### onThumbColor - Type: String | Titanium.UI.Color - Platforms: Android - Since: Titanium SDK 12.4.0 - Default: `undefined` The color used to tint the thumb icon of the switch when it is turned on. Android: Active thumb color of the Material Switch. ### onTintColor - Type: String | Titanium.UI.Color - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 12.4.0, iPhone 3.3.0, iPad 3.3.0 - Default: `undefined` The color used to tint the appearance of the switch when it is turned on. ### style - Type: Number - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 0.8.0, iPhone 10.0.0, iPad 10.0.0, macOS 10.0.0 - Default: `` Style of the switch. For Titanium versions older than 10.0.0, this is an Android only property and must be assigned a `SWITCH_STYLE_*` constant from the [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md) module. Accepts: `Titanium.UI.SWITCH_STYLE_CHECKBOX`, `Titanium.UI.SWITCH_STYLE_CHIP`, `Titanium.UI.SWITCH_STYLE_SLIDER`, `Titanium.UI.SWITCH_STYLE_TOGGLE_BUTTON` ### textAlign - Type: String | Number - Platforms: Android - Default: ` (toggle button, Android), (slider, Android), (checkbox, Android) ` Horizontal text alignment of the switch title. This property is only applicable when the switch [style](https://titaniumsdk.com/docs/sdk/Titanium.UI.Switch.md#style) is set to [SWITCH_STYLE_CHECKBOX](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#SWITCH_STYLE_CHECKBOX), [SWITCH_STYLE_SLIDER](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#SWITCH_STYLE_SLIDER), or [SWITCH_STYLE_TOGGLE_BUTTON](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#SWITCH_STYLE_TOGGLE_BUTTON), This property is only effective if the [width](https://titaniumsdk.com/docs/sdk/Titanium.UI.Switch.md#width) property is set to a value greater than the width of the [title](https://titaniumsdk.com/docs/sdk/Titanium.UI.Switch.md#title) contents. Accepts: `Titanium.UI.TEXT_ALIGNMENT_CENTER`, `Titanium.UI.TEXT_ALIGNMENT_JUSTIFY`, `Titanium.UI.TEXT_ALIGNMENT_LEFT`, `Titanium.UI.TEXT_ALIGNMENT_RIGHT` ### thumbColor - Type: String | Titanium.UI.Color - Platforms: Android - Since: Titanium SDK 12.4.0 - Default: `undefined` The color used to tint the thumb icon of the switch when it is turned off. Android: Inactive thumb color of the Material Switch. ### thumbTintColor - Type: String | Titanium.UI.Color - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 3.3.0 - Default: `undefined` The color used to tint the appearance of the thumb. ### tintColor - Type: String | Titanium.UI.Color - Platforms: Android, iPhone, iPad - Since: Titanium SDK Android 12.4.0, iPhone 3.3.0, iPad 3.3.0 - Default: `undefined` The color used to tint the outline of the switch when it is turned off. The color used to tint the outline of the switch when it is turned off. Android: Track color of the Material Switch. ### title - Type: String - Platforms: Android Text to display next to the switch, when the checkbox or slider style is in use. This property is only effective when the [style](https://titaniumsdk.com/docs/sdk/Titanium.UI.Switch.md#style) property is set to [SWITCH_STYLE_CHECKBOX](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#SWITCH_STYLE_CHECKBOX) or [SWITCH_STYLE_SLIDER](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#SWITCH_STYLE_SLIDER). Use the [textAlign](https://titaniumsdk.com/docs/sdk/Titanium.UI.Switch.md#textAlign) property to align this text within the switch. ### titleOff - Type: String - Platforms: Android - Default: `Off` Text to display on the switch in its "off" state, when the toggle button style is in use. Set to an empty string to remove title text. It is typically useful to set the `width` and/or `height` properties, to prevent the switch changing size between its on/off state. ### titleOn - Type: String - Platforms: Android - Default: `On` Text to display on the switch in its "on" state, when the toggle button style is in use. Set to an empty string to remove title text. It is typically useful to set the `width` and/or `height` properties, to prevent the switch changing size between its on/off state. ### value - Type: Boolean - Platforms: Android, iPhone, iPad, macOS - Default: `undefined (visual state off, Android)` Indicates whether the switch has been turned on or off by the user. May also be set programmatically. Set to `true` to turn on and `false` to turn off the switch. On Android, if this property is not defined, the rendered state of the switch is off. On iOS, be aware that this property must be set when the switch is rendered, otherwise it will not be visible. This is a known issue. ### verticalAlign - Type: Number | String - Platforms: Android - Default: `Titanium.UI.TEXT_VERTICAL_ALIGNMENT_CENTER` Vertical alignment for the text field. Accepts: `Titanium.UI.TEXT_VERTICAL_ALIGNMENT_BOTTOM`, `Titanium.UI.TEXT_VERTICAL_ALIGNMENT_CENTER`, `Titanium.UI.TEXT_VERTICAL_ALIGNMENT_TOP` ## Events ### change - Platforms: Android, iPhone, iPad, macOS Fired when the switch value changes. Event properties: - `value` (Boolean): New value of the switch. ### click - Platforms: Android Fired when the device detects a click against the view. There is a subtle difference between singletap and click events. A singletap event is generated when the user taps the screen briefly without moving their finger. This gesture will also generate a click event. However, a click event can also be generated when the user touches, moves their finger, and then removes it from the screen. The click event can also be generated by a trackball click. If you want to receive and trigger the value of switch, please use the `change` event instead. Event properties: - `x` (Number): X coordinate of the event from the `source` view's coordinate system. - `y` (Number): Y coordinate of the event from the `source` view's coordinate system. ## Inherited members 99 members are inherited. Each is documented on the type that declares it. - [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/main/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener` - [Titanium.UI.View](https://titaniumsdk.com/docs/sdk/main/Titanium.UI.View.md): `accessibilityDisableLongPress`, `accessibilityHidden`, `accessibilityHint`, `accessibilityLabel`, `accessibilityValue`, `anchorPoint`, `animate`, `animatedCenter`, `backgroundColor`, `backgroundDisabledColor`, `backgroundDisabledImage`, `backgroundFocusedColor`, `backgroundFocusedImage`, `backgroundGradient`, `backgroundImage`, `backgroundLeftCap`, `backgroundRepeat`, `backgroundSelectedColor`, `backgroundSelectedImage`, `backgroundTopCap`, `borderColor`, `borderRadius`, `borderWidth`, `bottom`, `center`, `clearMotionEffects`, `clipMode`, `convertPointToView`, `dblclick`, `doubletap`, `elevation`, `filterTouchesWhenObscured`, `focus`, `focusable`, `getViewById`, `height`, `hiddenBehavior`, `hide`, `horizontalMotionEffect`, `horizontalWrap`, `id`, `insertAt`, `keepHardwareMode`, `keepScreenOn`, `keypressed`, `layout`, `left`, `longclick`, `longpress`, `opacity`, `overrideCurrentAnimation`, `pinch`, `postlayout`, `previewContext`, `pullBackgroundColor`, `rect`, `right`, `rotate`, `rotation`, `rotationX`, `rotationY`, `scaleX`, `scaleY`, `show`, `singletap`, `size`, `softKeyboardOnFocus`, `stopAnimation`, `swipe`, `toImage`, `tooltip`, `top`, `touchEnabled`, `touchFeedback`, `touchFeedbackColor`, `touchcancel`, `touchend`, `touchmove`, `touchstart`, `transform`, `transitionName`, `translationX`, `translationY`, `translationZ`, `twofingertap`, `verticalMotionEffect`, `viewShadowColor`, `viewShadowOffset`, `viewShadowRadius`, `visible`, `width`, `zIndex` --- - This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1. - Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.