blob: 69b7d2d9088639adcbcdfdac8b1af151172ba994 [file] [log] [blame]
page.title=UI Widgets
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<li><a href="#recyclerview">RecyclerView</a></li>
<li><a href="#cardview">CardView</a></li>
<p>The support library in the Android L Developer Preview contains two new widgets,
<code>RecyclerView</code> and <code>CardView</code>. Use these widgets to show complex lists
and cards in your app. These widgets have material design style by default.</p>
<h2 id="recyclerview">RecyclerView</h2>
<p><code>RecyclerView</code> is a more advanced and flexible version of <code>ListView</code>.
This widget is a container for large sets of views that can be recycled and scrolled very
efficiently. Use the <code>RecyclerView</code> widget when you have lists with elements that
change dynamically.</p>
<p><code>RecyclerView</code> is easy to use, because it provides:</p>
<li>A layout manager for positioning items</li>
<li>Default animations for common item operations</li>
<p>You also have the flexibility to define custom layout managers and animations for this
<p>To use the <code>RecyclerView</code> widget, you have to specify an adapter and a layout
manager. To create an adapter, you extend the <code>RecyclerView.Adapter</code> class. The details
of the implementation depend on the specifics of your dataset and the type of views. For more
information, see the <a href="#rvexamples">examples</a> below.</p>
<img src="/preview/material/images/RecyclerView.png" alt="" id="figure1" style="width:550px"/>
<p class="img-caption">
  <strong>Figure 1</strong> - The <code>RecyclerView</code> widget.
<p>A <strong>layout manager</strong> positions item views inside a <code>RecyclerView</code> and
determines when to reuse item views that are no longer visible to the user. To reuse (or
<em>recycle</em>) a view, a layout manager may ask the adapter to replace the content of the
view with a different element from the dataset. Recycling views in this manner improves
performance by avoiding the creation of unnecessary views or performing expensive
<code>findViewById</code> lookups.
<p><code>RecyclerView</code> provides <code>LinearLayoutManager</code>, which shows the items in a
vertical or horizontal scrolling list. To create a custom layout, you extend the
<code>RecyclerView.LayoutManager</code> class.</p>
<p>Animations for adding and removing items are enabled by default in <code>RecyclerView</code>.
To customize these animations, extend the <code>RecyclerView.ItemAnimator</code> class and use
the <code>RecyclerView.setItemAnimator</code> method.</p>
<h3 id="rvexamples">Examples</h3>
<p>To include a <code>RecyclerView</code> in your layout:</p>
&lt;!-- A RecyclerView with some commonly used attributes -->
<p>To get the <code>RecyclerView</code> object in your activity:</p>
public class MyActivity extends Activity {
private RecyclerView mRecyclerView;
private RecyclerView.Adapter mAdapter;
private RecyclerView.LayoutManager mLayoutManager;
protected void onCreate(Bundle savedInstanceState) {
mRecyclerView = (RecyclerView) findViewById(;
// improve performance if you know that changes in content
// do not change the size of the RecyclerView
// use a linear layout manager
mLayoutManager = new LinearLayoutManager(this);
// specify an adapter (see also next example)
mAdapter = new MyAdapter(myDataset);
<p>To create a simple adapter:</p>
public class MyAdapter extends RecyclerView.Adapter&lt;MyAdapter.ViewHolder> {
private String[] mDataset;
// Provide a reference to the type of views that you are using
// (custom viewholder)
public static class ViewHolder extends RecyclerView.ViewHolder {
public TextView mTextView;
public ViewHolder(TextView v) {
mTextView = v;
// Provide a suitable constructor (depends on the kind of dataset)
public MyAdapter(String[] myDataset) {
mDataset = myDataset;
// Create new views (invoked by the layout manager)
public MyAdapter.ViewHolder onCreateViewHolder(ViewGroup parent,
int viewType) {
// create a new view
View v = LayoutInflater.from(parent.getContext())
.inflate(R.layout.my_text_view, parent, false);
// set the view's size, margins, paddings and layout parameters
ViewHolder vh = new ViewHolder(v);
return vh;
// Replace the contents of a view (invoked by the layout manager)
public void onBindViewHolder(ViewHolder holder, int position) {
// - get element from your dataset at this position
// - replace the contents of the view with that element
// Return the size of your dataset (invoked by the layout manager)
public int getItemCount() {
return mDataset.length;
<h2 id="cardview">CardView</h2>
<p><code>CardView</code> extends the <code>FrameLayout</code> class and lets you show information
inside cards that have a consistent look on any app. <code>CardView</code> widgets can have
shadows and rounded corners.</p>
<p>To create a card with a shadow, use the <code>android:elevation</code> attribute.
<code>CardView</code> uses real elevation and dynamic shadows
and falls back to a programmatic shadow implementation on earlier versions. For more information,
see <a href="{@docRoot}preview/material/compatibility.html">Compatibility</a>.</p>
<p>Here's how to specify properties of <code>CardView</code>:</p>
<li>To set the corner radius in your layouts, use the <code>card_view:cardCornerRadius</code>
<li>To set the corner radius in your code, use the <code>CardView.setRadius</code> method.</li>
<li>To set the background color of a card, use the <code>card_view:cardBackgroundColor</code>
<p>To include a <code>CardView</code> in your layout:</p>
&lt;!-- A CardView that contains a TextView -->
android:layout_height="match_parent" />