List in R: Create, Name, Index and Modify (Worked Example)

A list in R is an ordered collection of objects, called components, that can be of different types and lengths. You create one with list(), read a single component with [[ ]] or $, and read a sub-list with [ ]. This guide is for researchers who already have R running and need to hold a mixed set of results, such as a data frame, a numeric vector and a text label, in one object. It walks through one worked example with commands taken from R’s own documentation.

What a list is used for in research

R’s introductory manual defines it directly: “An R list is an object consisting of an ordered collection of objects known as its components.” Unlike an atomic vector, there is no need for the components to share a mode or type; the manual’s own examples list a numeric vector, a logical value, a matrix, a character array and a function as possible components. In analysis work that makes a list the natural container for things that belong together but are not the same shape, for example a dataset, its summary numbers and its provenance notes. Lists can also contain other lists, so they can be nested.

Two structures you already use are lists underneath. The manual states that “a data frame is a list with class data.frame“, and the base documentation notes that almost all lists in R are internally generic vectors. See the sibling guides on vectors in R and data frames in R for the structures a list is usually contrasted with, and R data types for the wider picture.

Install or access

Lists are part of base R, so nothing beyond R itself is needed. R is distributed from the Comprehensive R Archive Network (CRAN) at cran.r-project.org. If you work in an editor, RStudio runs the same commands; no package has to be loaded for any step below (package installation is covered in how to install R packages).

Step by step: build and use a list

1. Create a list (list in R example)

Call list() with the objects you want as components. Arguments can be named; if the names are omitted, the components are numbered only. The components are copied into the new list, and the originals are not affected.

study <- list(
  title    = "Pilot dose-finding study",
  n        = 40,
  arms     = c("control", "treatment"),
  complete = TRUE
)

The manual’s own version of this step is Lst <- list(name="Fred", wife="Mary", no.children=3, child.ages=c(4,7,9)).

2. Get the size of a list

The manual states that length(Lst) gives the number of top-level components. length(study) therefore returns 4. Components nested inside a component are not counted.

3. Index a list: [[ ]], $ and [ ]

Components are always numbered, and named components can also be reached by name. For the manual’s four-component list, Lst[[1]] to Lst[[4]] refer to the components in order, and Lst$name is the same as Lst[[1]]. With the example above:

study[[2]]          # the number 40 (component 2)
study$n             # same component, by name
study[["n"]]        # same component, name as a string
study$arms[2]       # second entry of the arms vector: "treatment"

Putting the name in a variable works with double brackets: the manual shows x <- "name"; Lst[[x]], the case where $ cannot be used. The manual also notes that component names may be abbreviated to the minimum letters needed to identify them uniquely (Lst$coe for Lst$coefficients).

The manual is emphatic that you must distinguish Lst[[1]] from Lst[1]:

Expression	What it returns (per R-intro, section 6.1)
study[[1]]	The first object in the list itself. If the list is named, the name is not included.
study[1]	A sub-list consisting of the first entry only. If the list is named, the names are transferred to the sub-list.

4. Name and rename components

Per the manual, the vector of names is an attribute of the list like any other and can be handled as such, so names(study) reads it and names(study) <- c(...) replaces it.

5. Add, change and delete components

Lists, like any subscripted object, can be extended by specifying additional components (the manual’s example is Lst[5] <- list(matrix=Mat)). Using a name does the same job:

study$site <- "Site A"      # adds a fifth component
study$n    <- 42             # replaces component n
study$complete <- NULL        # deletes component complete

The ?Extract documentation states that in all three kinds of replacement, “a value of NULL deletes the corresponding item of the list”, and that to set an entry to NULL instead you need x[i] <- list(NULL).

6. Combine (merge) lists

When c() is given list arguments, the result is a list whose components are those of the argument lists joined in sequence. The manual’s example is list.ABC <- c(list.A, list.B, list.C). This differs from c() on vectors, which joins everything into one vector (see also concatenation in R).

7. Apply a function to every component

lapply(X, FUN, ...) returns a list of the same length as X, each element being the result of applying FUN to the corresponding element. sapply() is a wrapper that by default returns a vector, matrix or array when that is possible. vapply() pre-specifies the type of return value, which the documentation describes as safer. For example, lapply(study, class) returns a list with one entry per component.

8. Convert between lists and vectors

as.list(x) coerces an object to a list and is.list(x) tests whether it is one. unlist(x) does the reverse: given a list structure, it simplifies it to a vector containing all the atomic components that occur in it. With the default recursive = TRUE it also unlists list components; recursive = FALSE stops at the first level. A vector has one type, so check the result of unlist() on a list of mixed types before using it. To inspect a list’s structure compactly, see str() in R.

Output and how to read it

• A printed list shows each component under its name ($n) or its position ([[1]]) followed by the component’s own value.
• If you pull a component with [[ ]] or $, you get the object itself and can index into it further, for example study$arms[2].
• If you pull with [ ], you get another list. This is why code that expects a number but receives a one-item list fails.
• lapply() output is always a list; sapply() output may be a vector or matrix.

Troubleshooting

Symptom	Cause and fix (source)
A calculation fails because a “number” is actually a list	You used [ ], which returns a sub-list. Use [[ ]] or $ to get the component itself (R-intro 6.1).
Asking for a component by a name that does not exist gives NULL	Per ?Extract, attempts to extract a non-existent element by name return NULL. Check names(x) for spelling.
$ picks an unexpected component	Names can be abbreviated to a unique prefix (R-intro 6.1). Use [["exact_name"]] when you want an exact name.
A component vanished when you meant to set it to NULL	Assigning NULL removes the item. To keep a NULL entry use x[i] <- list(NULL) (?Extract).
$ used on an atomic vector	?Extract states $ is only valid for recursive objects (and NULL). Convert with as.list() first, or use [[ ]].

Related structures in R

Structure	How it relates to a list (source)
Atomic vector	All elements share one type; a list’s components need not (R-intro 6.1). See vectors in R.
Data frame	A list with class data.frame; vector components must all have the same length (R-intro 6.3). See data frames in R.
Environment	Convertible with as.list(); the base documentation’s example sets e1$a and e1$b and calls as.list(e1).

Frequently asked questions

What is a list in R?

An ordered collection of objects (components) that need not share a type. It is created with list() and can hold vectors, matrices, functions and other lists.

How do I get the size of a list in R?

Use length(x), which gives the number of top-level components.

What is the difference between [[ ]] and [ ] on a list?

[[ ]] selects a single element; [ ] returns a sub-list, keeping names.

Is a data frame a list?

Yes. R’s manual describes a data frame as a list with class data.frame, with the extra restriction that its vector components have the same length.

How do I merge two lists?

c(list.A, list.B) returns one list whose components are those of both, in sequence.

How do I turn a list into a vector?

unlist() simplifies a list to a vector of its atomic components; mixed types are coerced to a common type.

Sources (official documentation, read 2026-11-07)

• R Core Team, An Introduction to R, chapter 6 “Lists and data frames”: cran.r-project.org/doc/manuals/r-release/R-intro.html
• R base documentation, list / as.list / is.list: stat.ethz.ch/R-manual/R-devel/library/base/html/list.html
• R base documentation, Extract: stat.ethz.ch/R-manual/R-devel/library/base/html/Extract.html
• R base documentation, lapply and unlist