Titanium SDK UI expert

A practical guide to Titanium SDK UI. Covers layouts, event handling, animations, performance, and platform-specific components for iOS and Android.

Project detection

:::info auto-detects titanium projects This skill detects Titanium projects and provides UI guidance.

Detection happens automatically. You do not need to run a command.

Titanium project indicator:

• tiapp.xml (required for all Titanium projects)

Applicable to both:

• Alloy projects (app/ folder structure)
• Classic projects (Resources/ folder)

Behavior based on detection:

• Titanium detected: Provide UI guidance for Alloy and Classic, ListView/TableView patterns, and platform differences
• Not detected: State this is for Titanium projects only and skip UI guidance :::

Quick reference

Critical rules

Performance

• Do not use Ti.UI.SIZE in ListViews. It causes jerky scrolling. Use fixed heights.
• Prefer ListView over TableView for new apps with large datasets.
• Batch updates with applyProperties to reduce bridge overhead.
• Avoid WebView inside TableView. It kills scrolling performance.

iOS accessibility

• Do not set accessibility properties on container views. It blocks child interaction.
• Do not set accessibilityLabel on text controls on Android. It overrides visible text.

Layout

• Use dp units for cross-platform consistency.
• Android ScrollView is vertical or horizontal, not both. Set scrollType.

Platform-specific properties

:::danger critical: platform-specific properties require modifiers Using Ti.UI.iOS.* or Ti.UI.Android.* properties without platform modifiers will crash cross-platform compilation.

Example of the damage:

// Wrong: adds Ti.UI.iOS to an Android build
const win = Ti.UI.createWindow({
  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
})

Correct approaches:

Option 1: TSS modifier (Alloy projects):

"#mainWindow[platform=ios]": {
  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
}

Option 2: Conditional code:

if (OS_IOS) {
  $.mainWindow.statusBarStyle = Ti.UI.iOS.StatusBar.LIGHT_CONTENT
}

Properties that always require platform modifiers:

• iOS: statusBarStyle, modalStyle, modalTransitionStyle, any Ti.UI.iOS.*
• Android: actionBar config, any Ti.UI.Android.* constant

For platform-specific UI patterns, see platform-ui-ios.md and platform-ui-android.md. :::

Event management

• Remove global listeners (Ti.App, Ti.Gesture, Ti.Accelerometer) on pause to save battery.
• Input events bubble up. System events do not.

App architecture

• Limit tabs to 4 or fewer for better UX across platforms.
• Use NavigationWindow for iOS hierarchical navigation.
• Handle androidback to prevent unexpected exits.

Platform differences summary

UI design workflow

1. Choose app structure: tab-based or window-based
2. Pick a layout mode: composite, vertical, or horizontal
3. Decide sizing: SIZE or FILL based on component defaults
4. Plan events: bubbling, app-level events, lifecycle
5. Optimize performance: templates, batch updates
6. Apply accessibility per platform
7. Add motion: animations, 2D/3D transforms, transitions

Searching references

When you need specific patterns, grep these terms in the reference files:

• App structure: TabGroup, NavigationWindow, modal, execution context, androidback
• Layouts: dp, Ti.UI.SIZE, Ti.UI.FILL, composite, vertical, horizontal
• Events: addEventListener, cancelBubble, bubbling, Ti.App.fireEvent
• TableView: TableView, TableViewRow, setData, appendRow, className
• ListView: ItemTemplate, bindId, setItems, updateItemAt, marker
• Gestures: swipe, pinch, longpress, shake, accelerometer
• Animation: animate, create2DMatrix, create3DMatrix, autoreverse
• Fonts: fontFamily, PostScript, createAttributedString, ATTRIBUTE_
• Icons/splash: DefaultIcon, appicon, nine-patch, drawable, splash, iTunesArtwork, adaptive
• Android: Action Bar, onCreateOptionsMenu, theme, Material3, talkback
• iOS: 3D Touch, Popover, SplitWindow, badge, NavigationWindow
• Accessibility: accessibilityLabel, VoiceOver, TalkBack, accessibilityHidden

Related skills

For work beyond UI components, use these skills: