> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: $w

## Namespace: mobile-repeater

## Article: Introduction

## Article Link: https://dev.wix.com/docs/velo/velo-only-apis/$w/mobile-repeater/introduction.md

## Article Content:

# Introduction
<blockquote class="important">

__Important:__
+ This API is only relevant for custom widgets in [Branded Apps](https://www.wix.com/app-builder).
+ Custom widgets are not yet available to all users. 
+ This API is in [Developer Preview](https://www.wix.com/velo/reference/api-overview/developer-preview) and is subject to change. 

</blockquote>

 Repeaters provide a way for you to add repeating content to a widget.
 Repeaters consist of repeating items, each with the same layout
 but different data.

 For example, the repeater below contains three items, each with the same
 layout. There is an image on the left and two text elements on the right.
 However, the data in each item is different. That is, the actual images and
 text values are different in each repeated item.

 ![Mobile repeater example](images/mobile-repeater.png "Mobile repeater example")

 The data displayed in a repeater comes from either:

 + Connecting the repeater and the elements contained within its items to a
   dataset in the Editor.
 + Using the [`data`](#data) property in conjunction with the [`forEachItem()`](#forEachItem),
   [`forItems()`](#forItems), and [`onItemReady()`](#onItemReady) functions
   in code.

 Check out our [Hello Repeaters](https://dev.wix.com/docs/coding-examples/getting-started/hello-world/hello-repeaters.md)
 example, which demonstrates how to use repeaters for websites. Since the functionality of repeaters for websites closely resembles that of repeaters for 
 mobile app widgets, this example can be a valuable resource for helping you understand and become familiar with repeaters. 

 ### Repeated Item Template

 Each repeater has an item template that contains the elements and initial data
 that are used when new items are created. The template's initial state is the
 state of the first repeated item that appears in the Editor. Using code, you
 can set the properties of, get the properties of, or call functions on the
 elements of the item template by selecting the elements using
 [`$w()`]($w.html#w), the [global scope](#global-scope) selector function.

 ### Selector Scope

 Selector functions are used to select specific elements so you can work
 with them in code. Depending on which selector you use, you are able to
 select elements from the different scopes described below.

 There are two types of selector functions:

 + [Global Scope Selectors](#global-scope)
 + [Repeated Item Scope Selectors](#repeated-item-scope)


 #### Global Scope

 The [`$w()`]($w.html#w) function that is available to your widget code selects elements in the global scope.

 A selector with global scope can be used to select any element that is not
 contained in a repeater. You can also use it to select an element that is
 contained in a repeater, but you need to understand what that selection means.

 When you select an element contained in a repeater from the global scope and
 you get the value of one of the element's properties, you receive the value
 of that element's property from the repeater's [item template](#repeated-item-template).

 For example, here `templateText` is the `text` value of the `myRepeatedText`
 element from the repeater's item template.

 ```javascript
 $w.onReady( function () {
   let templateText = $w("#myRepeatedText").text;
 } );
 ```

 When you select an element contained in a repeater from the global scope and
 you set the value of one of the element's properties or call one of the
 element's functions, the value is set or the function is called on the
 repeater's [item template](#repeated-item-template) **and** all repeated instances of
 that element.


 For example, here the item template is changed so that `"New Text"` is the
 `text` value of the `myRepeatedText` element. Also, all existing repeated
 items have the `text` value of their `myRepeatedText` element set to `"New Text"`.

 ```javascript
 $w.onReady( function () {
   $w("#myRepeatedText").text = "New Text";
 } );
 ```

 And here the item template is changed so that the `myRepeatedMobileImage` element
 is hidden. Also, all existing repeated items have their `myRepeatedMobileImage` element hidden.

 ```javascript
 $w.onReady( function () {
   $w("#myRepeatedMobileImage").hide();
 } );
 ```

 #### Repeated Item Scope

 There are two instances where you get a repeated-item-scope selector:

 + The `$item` parameter of the [`forEachItem()`](#forEachItem),
   [`forItems()`](#forItems), and [`onItemReady()`](#onItemReady) event
   handlers.
 + When calling the [$w.at()]($w.html#at) and passing it an event whose
   [`context`]($w/at) is "COMPONENT_SCOPE". This is usually
   done in an event handler that handles event on an element inside a repeater.


 A selector with repeated item scope can be used to select a specific instance
 of a repeating element.

 For example, here when the `myRepeatedMobileImage` element is pressed, the value of
 a text element in the same repeated item where the mobile image was pressed is changed
 to "Selected". All the other text elements with the ID `myRepeatedText`
 in the other items of the repeater are not affected.

 ```javascript
 $w.onReady( function () {
   $w("#myRepeatedMobileImage").onPress( (event) => {
     let $item = $w.at(event.context);
     $item("#myRepeatedText").text = "Selected";
   } );
 } );
 ```

 And here, when each item is ready, the value of a text element is set to a
 value found in that specific item's data.

 ```javascript
 $w("#myMobileRepeater").onItemReady( ($item, itemData, index) => {
   $item("#myRepeatedText").text = itemData.textField;
 } );
 ```

 You can also use a selector with repeated item scope to select non-repeating
 elements from the global scope. However, you cannot change a repeater's
 [item template](#repeated-item-template) using a selector with repeated item scope.

 You can restrict a selector with repeated item scope to only select
 elements from the current repeated items and their descendants, but not elements
 from the global scope by adding `.scoped()` to the selector so the function
 call looks like `$item.scoped("#idToSelect")`.

 ### Retrieve Repeater Item Data When Pressed

 Each repeated item in a repeater has a [`MobileContainer`]($w.MobileContainer.html) element
 that holds all of its repeated elements. To retrieve the data associated
 with a specific repeated item when it is pressed, create an `onPress` event
 handler for the item's `MobileContainer`. Depending on how you populated the repeater
 with data, you either use the connected dataset or the repeater's `data`
 array to retrieve the pressed item's data in the event handler.

 For a repeater populated by connecting it to a dataset:

 ```javascript
 $w.onReady( function () {
   $w("#repeatedMobileContainer").onPress( (event) => {
     let $item = $w.at(event.context);
     let pressedItemData = $item("#myDataset").getCurrentItem();
   } );
 } );
 ```

 For a repeater populated by setting its [`data`](#data) property:

 ```javascript
 $w.onReady( function () {
   $w("#repeatedMobileContainer").onPress( (event) => {
     const data = $w("#myMobileRepeater").data;
     let pressedItemData = data.find(item => item._id === event.context.itemId);
   } );
 } );
 ```
> Learn more about repeaters in [Getting Started](/getting-started/working-with-repeaters) and on [Wix Learn](https://www.wix.com/learn/online-course/coding-with-velo/velo-repeaters).