Repeaters provide a way for you to add repeating content to a page. 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.
The data displayed in a repeater comes from either:
data
property in conjunction with the forEachItem()
,
forItems()
, and onItemReady()
functions
in code.Get hands-on experience with repeaters on our Hello Repeaters example page.
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()
, the global scope selector function.
Selector functions are used to select specific page 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:
The $w()
function that is available to your Page
and Site 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.
For example, here templateText
is the text
value of the myRepeatedText
element from the repeater's item template.
1
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 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"
.
1
And here the item template is changed so that the myRepeatedImage
element
is hidden. Also, all existing repeated items have their myRepeatedImage
element hidden.
1
There are two instances where you get a repeated-item-scope selector:
$item
parameter of the forEachItem()
,
forItems()
, and onItemReady()
event
handlers.context
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 myRepeatedImage
element is clicked, the value of
a text element in the same repeated item where the image was clicked is changed
to "Selected". All the other text elements elements with the ID myRepeatedText
in the other items of the repeater are not affected.
1
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.
1
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 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")
.
Each repeated item in a repeater has a Container
element
that holds all of its repeated elements. To retrieve the data associated
with a specific repeated item when it is clicked, create an onClick
event
handler for the item's Container
. Depending on how you populated the repeater
with data, you either use the connected dataset or the repeater's data
array to retrieve the clicked item's data in the event handler.
For a repeater populated by connecting it to a dataset:
1
For a repeater populated by setting its data
property:
1
Learn more about repeaters in Getting Started and on Wix Learn.