# Titanium.UI.ScrollView

> A view that contains a horizontally and/or vertically-scrollable region of content.

- Source: https://titaniumsdk.com/docs/sdk/13.2.0/Titanium.UI.ScrollView
- Titanium SDK version: 13.2.0
- Kind: view
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 0.9
- Extends: Titanium.UI.View
- Inheritance: Titanium.UI.View > Titanium.Proxy

Use the [Titanium.UI.createScrollView](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#createScrollView) method or **`<ScrollView>`** Alloy element to create a scroll view.

Views added to the scroll view will be scrolled based on the size of the scrollable region of
content. If a scrollable region fits within the size of its scroll view, the view will not
scroll.

#### Android Platform Notes

On Android, a scroll view can only scroll in one direction, either vertically or horizontally,
and not both at the same time. The [Titanium.UI.ScrollView.scrollType](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollView.md#scrollType) property sets the scroll
direction explicitly. If the `scrollType` property is not assigned a value, the scroll view
attempts to determine the scroll direction based on some the following rules:

* If [Titanium.UI.ScrollView.contentWidth](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollView.md#contentWidth) and [Titanium.UI.ScrollView.width](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollView.md#width) are both
set and are equal to each other, or if they are both set
*and* `showVerticalScrollIndicator` is set to `true`, then the scroll direction is set to
"vertical".

* If [Titanium.UI.ScrollView.contentHeight](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollView.md#contentHeight) and [Titanium.UI.ScrollView.height](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollView.md#height) are
both set and are equal, or if they are both set and [Titanium.UI.ScrollView.showHorizontalScrollIndicator](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollView.md#showHorizontalScrollIndicator) is set to
`true`, then the scroll direction is set to "horizontal".

Pinching a `ScrollableView` to zoom in and out of content is not supported on Android. On iOS, this action
is natively supported by the UIScrollView class, but on Android, the native ScrollView class does
not support this action.

## Example: Simple Scroll View

Create a scroll view with content.

``` js
var win = Ti.UI.createWindow({
  exitOnClose: true,
  fullscreen: false,
  title: 'ScrollView Demo'
});

var scrollView = Ti.UI.createScrollView({
  showVerticalScrollIndicator: true,
  showHorizontalScrollIndicator: true,
  height: '80%',
  width: '80%'
});
var view = Ti.UI.createView({
  backgroundColor:'#336699',
  borderRadius: 10,
  top: 10,
  height: 2000,
  width: 1000
});
scrollView.add(view);
win.add(scrollView);
win.open();
```

## Example: Scroll View as a Table View

Create a scroll view that contains a set of views in a layout to resemble a table view with
rows. This approach can mitigate the native Android issue described in the "TextFields in
Tables with SOFT_INPUT_ADJUST_PAN" section of <Titanium.UI.TableView>.

``` js
var win = Ti.UI.createWindow();

if (Ti.UI.Android){
  win.windowSoftInputMode = Ti.UI.Android.SOFT_INPUT_ADJUST_PAN;
}

function createRow(i) {
  var row = Ti.UI.createView({
    backgroundColor: 'white',
    borderColor: '#bbb',
    borderWidth: 1,
    width:'100%', height: 70,
    top: 0, left: 0
  });
  var inputTextField = Ti.UI.createTextField({
    hintText: 'Enter value ' + i,
    keyboardType: Ti.UI.KEYBOARD_NUMBERS_PUNCTUATION,
    top: 10, left: '10%',
    width: '80%', height: 60
  });
  row.add(inputTextField);
  return row;
}

var scrollView = Ti.UI.createScrollView({
  bottom:120,
  layout: 'vertical'
});

for(var i = 0; i <= 20; i++){
var row = createRow(i);
  scrollView.add(row);
}
win.add(scrollView);

var label = Ti.UI.createLabel({
  backgroundColor:'darkgray',
  text: 'Your advert here',
  textAlign: 'center',
  bottom:0,
  width: Titanium.UI.FILL,
  height:100
});
win.add(label);
win.open();
```

## Example: Alloy XML Markup

Previous simple scroll view example as an Alloy view.

 ``` xml
 <Alloy>
     <Window id="win" backgroundColor="white" exitOnClose="true" fullscreen="false" title="ScrollView Demo">
         <ScrollView id="scrollView" showVerticalScrollIndicator="true" showHorizontalScrollIndicator="true" height="80%" width="80%">
             <View id="view" backgroundColor="#336699" borderRadius="10" top="10" height="2000" width="1000" />
         </ScrollView>
     </Window>
 </Alloy>
 ```

## Properties

### canCancelEvents

- Type: Boolean
- Platforms: Android, iPhone, iPad, macOS
- Default: `true`

Determines whether this scroll view can cancel subview touches in order to scroll instead.

On iOS, this property maps to the native `canCancelContentTouches` property which controls
whether touches in the content view always lead to tracking. See [UIScrollView](https://developer.apple.com/documentation/uikit/uiscrollview) for more details.

On Android, setting this property to false prevents the scroll view from intercepting
any touch events from its subviews. Note that this behavior may be slightly different from iOS.

### contentHeight

- Type: Number | String
- Platforms: Android, iPhone, iPad, macOS

Height of the scrollable region.

While absolute dimensions are supported, relative values, such as those provided
in percentages, are not. The minimum value for contentHeight is the height of the scroll view.
Measured in platform-specific units; pixels on Android, effective pixels on Windows and density-independent pixels (dip) on iOS.

### contentOffset

- Type: Point
- Platforms: Android, iPhone, iPad, macOS

X and Y coordinates to which to reposition the top-left point of the scrollable region.

On iOS, a new value causes the scroll view to perform an animated scroll to the new offset.
The [Titanium.UI.ScrollView.setContentOffset](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollView.md#setContentOffset) method can be used to prevent this animation.

### contentWidth

- Type: Number | String
- Platforms: Android, iPhone, iPad, macOS

Width of the scrollable region.

While absolute dimensions are supported, relative values, such as those provided
in percentages, are not. The minimum value for contentWidth is the width of the scroll view.
Measured in platform-specific units; pixels on Android, effective pixels on Windows and density-independent pixels (dip) on iOS.

### decelerationRate

- Type: Number
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.2.3
- Default: `Undefined.`

The deceleration rate of the ScrollView.

Accepts: `Titanium.UI.iOS.SCROLL_DECELERATION_RATE_FAST`, `Titanium.UI.iOS.SCROLL_DECELERATION_RATE_NORMAL`

### disableBounce

- Type: Boolean
- Platforms: iPhone, iPad, macOS
- Default: `false`

Determines whether scroll bounce of the scrollable region is enabled.

Set to `true` to disable horizontal and vertical bounce.

This property takes precedence over the `horizontalBounce` and `verticalBounce` properties.

### edgeEffect

- Type: Dictionary
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 13.1.0
- Requires: iOS 26.0+

Configures the edge effects displayed when the scroll view hits its bounds.

Provide a dictionary with `top`, `right`, `bottom`, and `left` keys set to the
`Titanium.UI.iOS.SCROLL_VIEW_EDGE_EFFECT_STYLE_*` constants to control each edge
individually. Requires a [Titanium.UI.NavigationWindow](https://titaniumsdk.com/docs/sdk/Titanium.UI.NavigationWindow.md) to apply the effect style.

### horizontalBounce

- Type: Boolean
- Platforms: iPhone, iPad, macOS
- Default: `true`

Determines whether horizontal scroll bounce of the scrollable region is enabled.

With the default value of `true`, dragging in the horizontal direction is always allowed and
also bounces.

Set to `false` to disable horizontal scroll bounce if the horizontal content is smaller than
the scroll view bounds. However, larger content will still bounce when scrolled.

Note that the `disableBounce` property takes precedence over the `horizontalBounce` and
`verticalBounce` properties.

### keyboardDismissMode

- Type: Number
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 6.0.0
- Default: `Undefined (behaves like Titanium.UI.iOS.KEYBOARD_DISMISS_MODE_NONE)`

The manner in which the keyboard is dismissed when a drag begins in the scroll view.

Accepts: `Titanium.UI.iOS.KEYBOARD_DISMISS_MODE_INTERACTIVE`, `Titanium.UI.iOS.KEYBOARD_DISMISS_MODE_NONE`, `Titanium.UI.iOS.KEYBOARD_DISMISS_MODE_ON_DRAG`

### maxZoomScale

- Type: Number
- Platforms: iPhone, iPad, macOS
- Default: `1`

Maximum scaling factor of the scrollable region and its content.

This value determines how large the content can be scaled.
It must be greater than the [minimum zoom scale](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollView.md#minZoomScale) for zooming to be enabled.
The default value is 1.0 unless otherwise specified.

Note that specifying a value less than or equal to 0 will hide all contents of the scroll view.

### minZoomScale

- Type: Number
- Platforms: iPhone, iPad, macOS
- Default: `1`

Minimum scaling factor of the scrollable region and its content.

This value determines how small the content can be scaled.
It must be less than the [maximum zoom scale](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollView.md#maxZoomScale) for zooming to be enabled.
The default value is 1.0 unless otherwise specified.

### overScrollMode

- Type: Number
- Platforms: Android
- Since: Titanium SDK 3.1.0
- Default: `Titanium.UI.Android.OVER_SCROLL_ALWAYS`

Determines the behavior when the user overscolls the view.

Accepts: `Titanium.UI.Android.OVER_SCROLL_ALWAYS`, `Titanium.UI.Android.OVER_SCROLL_IF_CONTENT_SCROLLS`, `Titanium.UI.Android.OVER_SCROLL_NEVER`

### refreshControl

- Type: Titanium.UI.RefreshControl
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 6.3.0, iPhone 6.0.0, iPad 6.0.0

View positioned above the first row that is only revealed when the user drags the scroll view contents down.

An alternate to the pullView property. See [Titanium.UI.RefreshControl](https://titaniumsdk.com/docs/sdk/Titanium.UI.RefreshControl.md) for usage and examples. Since Titanium
SDK 7.5.0, the RefreshControl API is also available on iOS < 10.

### scrollIndicatorStyle

- Type: Number
- Platforms: iPhone, iPad, macOS
- Default: `Titanium.UI.iOS.ScrollIndicatorStyle.DEFAULT`

Style of the scrollbar.

Accepts: `Titanium.UI.iOS.ScrollIndicatorStyle.BLACK`, `Titanium.UI.iOS.ScrollIndicatorStyle.DEFAULT`, `Titanium.UI.iOS.ScrollIndicatorStyle.WHITE`

### scrollingEnabled

- Type: Boolean
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 3.0.0
- Default: `true`

Determines whether scrolling is enabled for the view.

### scrollsToTop

- Type: Boolean
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 2.0.0
- Default: `true`

Controls whether the scroll-to-top gesture is effective.

The scroll-to-top gesture is a tap on the status bar; The default value of this property is true.
This gesture works when you have a single visible scroll view.
If there are multiple table views, web views, text areas, and/or scroll views visible,
you will need to disable (set to false) on the above views that you don't want this
behaviour on. The remaining view will then respond to scroll-to-top gesture.

### scrollType

- Type: String
- Platforms: Android

Limits the direction of the scrollable region, overriding the deduced setting. Set to
`horizontal` or `vertical`.

See the [scrollView](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollView.md) description for more details about how the
scroll direction is deduced when this property is not defined.

### showHorizontalScrollIndicator

- Type: Boolean
- Platforms: Android, iPhone, iPad, macOS
- Default: `false`

Determines whether the horizontal scroll indicator is visible.

Set to `true` to show the horizontal scroll indicator.

### showVerticalScrollIndicator

- Type: Boolean
- Platforms: Android, iPhone, iPad, macOS
- Default: `false`

Determines whether the vertical scroll indicator is visible.

Set to `true` to show the vertical scroll indicator.

### verticalBounce

- Type: Boolean
- Platforms: iPhone, iPad, macOS
- Default: `true`

Determines whether vertical scroll bounce of the scrollable region is enabled.

With the default value of `true`, dragging in the vertical direction is always allowed and
also bounces.

Set to `false` to disable vertical scroll bounce if the vertical content is smaller than
the scroll view bounds. However, larger content will still bounce when scrolled.

Note that the `disableBounce` property takes precedence over the `horizontalBounce` and
`verticalBounce` properties.

### zoomScale

- Type: Number
- Platforms: iPhone, iPad, macOS
- Default: `1`

Scaling factor of the scroll view's content.

This value is bound by the [minZoomScale](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollView.md#minZoomScale) and [maxZoomScale](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollView.md#maxZoomScale) properties.

## Methods

### scrollTo

- Platforms: Android, iPhone, iPad, macOS

Moves the specified coordinate of the scrollable region into the viewable area.

Parameters:

- `x` (Number): X coordinate from the scrollable region's coordinate system.
- `y` (Number): Y coordinate from the scrollable region's coordinate system.
- `options` (AnimatedOptions, optional): A simple object for specifying the animation properties when scrolling the view (since SDK 6.1.0). When set to `{ animated: true }` it will scroll smoothly to the destination. Note that the default here is equivalent to passing in `{ animated: true }` Default: `{ animated: true }`.

### scrollToBottom

- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 2.1.0

Moves the end of the scrollable region into the viewable area.

On Android the behavior of `scrollToBottom` depends on whether this scroll view scrolls
horizontally or vertically. For vertical scroll views, `scrollToBottom` moves the bottom
of the scrollable region into the viewable area. For horizontal scroll views,
`scrollToBottom` moves the rightmost edge of of the scrollable region into the viewable area.

On iOS, `scrollToBottom` moves the bottom-right corner of the scrollable region into the
viewable area.

### scrollToTop

- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 7.0.0

Moves the top of the scrollable region into the viewable area.

On Android the behavior of `scrollToTop` depends on whether this scroll view scrolls
horizontally or vertically. For vertical scroll views, `scrollToTop` moves the top
of the scrollable region into the viewable area. For horizontal scroll views,
`scrollToTop` moves the leftmost edge of of the scrollable region into the viewable area.

On iOS, `scrollToTop` moves the top-left corner of the scrollable region into the
viewable area.

### setContentOffset

- Platforms: iPhone, iPad, macOS

Sets the value of the [contentOffset](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollView.md#contentOffset) property.

Parameters:

- `contentOffsetXY` (Point): X and Y coordinates to which to reposition the top-left point of the scrollable region.
- `animated` (AnimatedOptions, optional): A JS object with an `animated` property which determines whether the scrollable region reposition should be animated. Note that the default here is equivalent to passing in `{ animated: true }` Default: `{ animated: true }`.

### setZoomScale

- Platforms: iPhone, iPad, macOS

Sets the value of the [zoomScale](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollView.md#zoomScale) property.

Parameters:

- `zoomScale` (Number): Scaling factor of the scroll view's content.
- `options` (AnimatedOptions, optional): A JS object with an `animated` property which determines whether the scrollable region reposition should be animated Note that the default here is equivalent to passing in `{ animated: false }` Default: `{ animated: false }`.

## Events

### dragend

- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK iPhone 3.0.0, iPad 3.0.0, Android 6.2.0

Fired when the scrollable region stops being dragged.

A dragging gesture is when a touch remains in contact with the display to physically drag
the view, as opposed to it being the result of scrolling momentum.

Event properties:

- `decelerate` (Boolean): Indicates whether scrolling will continue but decelerate, now that the drag gesture has been released by the touch. If `false`, scrolling will stop immediately. Is always `true` on Android.
- `x` (Number): X coordinate from the scrollable touch position.
- `y` (Number): Y coordinate from the scrollable touch position.

### dragEnd

- Platforms: iPhone, iPad, macOS

Fired when the scrollable region stops being dragged.

This event has been deprecated and renamed dragend (lower case).

A dragging gesture is when a touch remains in contact with the display to physically drag
the view, as opposed to it being the result of scrolling momentum.

Event properties:

- `decelerate` (Boolean): Indicates whether scrolling will continue but decelerate, now that the drag gesture has been released by the touch. If `false`, scrolling will stop immediately.

### dragstart

- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK iPhone 3.0.0, iPad 3.0.0, Android 6.2.0

Fired when the scrollable region starts being dragged.

A dragging gesture is when a touch remains in contact with the display to physically drag
the view, as opposed to it being the result of scrolling momentum.

Event properties:

- `x` (Number): X coordinate from the scrollable touch position.
- `y` (Number): Y coordinate from the scrollable touch position.

### dragStart

- Platforms: iPhone, iPad, macOS

Fired when the scrollable region starts being dragged.

This event has been deprecated and renamed dragstart (lower case).

A dragging gesture is when a touch remains in contact with the display to physically drag
the view, as opposed to it being the result of scrolling momentum.

### scale

- Platforms: iPhone, iPad, macOS

Fired when the zoom scale factor changes.

Event properties:

- `scale` (Number): New scaling factor as a float.

### scroll

- Platforms: Android, iPhone, iPad, macOS

Fired when the scrollable region is scrolled.

Event properties:

- `contentSize` (Size): The current content size of the scroll view defined by its `width` and `height` properties.
- `decelerating` (Boolean): Indicates whether the scroll is decelerating.
- `dragging` (Boolean): Indicates whether the event was fired during a dragging gesture, where the touch remained in contact with the display to physically drag the view, as opposed to it being the result of scrolling momentum.
- `zooming` (Boolean): Indicates whether the event was fired during a zooming operation. This is only available from Release 3.2.3 of the Titanium Mobile SDK.
- `curZoomScale` (Number): The current scaling factor of the scroll view content. This might not be equal to the `zoomScale` property or be within the range specified by `minZoomScale` and `maxZoomScale`. This is only available from Release 3.2.3 of the Titanium Mobile SDK.
- `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

106 members are inherited. Each is documented on the type that declares it.

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/13.2.0/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener`
- [Titanium.UI.View](https://titaniumsdk.com/docs/sdk/13.2.0/Titanium.UI.View.md): `accessibilityDisableLongPress`, `accessibilityHidden`, `accessibilityHint`, `accessibilityLabel`, `accessibilityValue`, `add`, `anchorPoint`, `animate`, `animatedCenter`, `backgroundColor`, `backgroundDisabledColor`, `backgroundDisabledImage`, `backgroundFocusedColor`, `backgroundFocusedImage`, `backgroundGradient`, `backgroundImage`, `backgroundLeftCap`, `backgroundRepeat`, `backgroundSelectedColor`, `backgroundSelectedImage`, `backgroundTopCap`, `borderColor`, `borderRadius`, `borderWidth`, `bottom`, `center`, `children`, `clearMotionEffects`, `click`, `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`, `remove`, `removeAllChildren`, `replaceAt`, `right`, `rotate`, `rotation`, `rotationX`, `rotationY`, `scaleX`, `scaleY`, `show`, `singletap`, `size`, `softKeyboardOnFocus`, `stopAnimation`, `swipe`, `tintColor`, `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`.