Last updated August 24, 2016. Created on August 23, 2010.
Edited by hbowie, arianek, agentrickard. Log in to edit this page.

The List module defines various fields for storing a list of items, for use with the Field module. Usually these items are entered through a select list, checkboxes or radio buttons. This module is an internal element of the Field API.

Creating a list field

Creating a list field


List module defines and creates interface elements for select lists, checkboxes and radio buttons used by the Field UI. When creating new fields for content nodes or users, you may use the four basic list options when creating fields:

  1. List - The default list type, a simple selection of text options, for example:

    This field type stores values based on the order of each item. Altering the options after creating the field can result in lost data. These values may not have optional display labels. To use labels with named keys, select the List Text field format.

  2. Boolean - Creates a single yes/no option. When creating this field, you may select two radio buttons or a single on/off checkbox. When creating boolean fields, you supply labels for the on and off states. Note that changing the labels after creating the field will not affect existing data.
  3. List (numeric) - Creates a list of items with associated numeric keys, such that the order of elements does not matter for data storage. This type is suitable for most lists, as it allows human-readable labels, for example:

    These labels may contain limited HTML for formatting the forms created by your field. Changing the labels after creating the field is acceptable. Changing the numeric keys may result in a loss of data. Note that leading zeroes on any of the integer keys should be omitted, as they will cause problems.

  4. List (text) - Creates a list of items with text keys for data storage. These lists are useful for storing data which has meaningful text keys, such as the abbreviations of countries:
    US|United States

    These labels may contain limited HTML for formatting the forms created by your field. Changing the labels after creating the field is acceptable. Changing the text keys may result in a loss of data.

Entering field options

When entering field options, you are creating a list that Drupal can present to your users. Each element in the list is defined by a linebreak, so you must enter one item per line.


US|United States


United States


Canada, Mexico, United States


Canada|Mexico|United States

About field labels

Field labels are used to provide human-readable form elements. The keys of each key|label pair are stored in the database, while the labels are displayed to site users. When entering keys and labels, use the pipe character | to separate the key from the label.

Labels may contain limited HTML to improve form readability. For example, you may provide help links for an item or use emphasis:

CA|Canada (<a href="">Wikipedia entry</a>)
US|United States


Drupal 7

This module was introduced in Drupal 7.

CCK in Drupal 6 and lower

In Drupal 6, list field behavior was defined by the contributed CCK module.


Default module: Yes
Dependencies: Field
Related Modules: Field UI, Field SQL Storage, File, Image, Number, Text
Permissions: None.
API Documentation: Field types API
Database tables: None.

Looking for support? Visit the forums, or join #drupal-support in IRC.


jimvenet’s picture

Is there a way to get the field list options from the database? I basically need to create a field list that allow you to choose among the node names... so the only solution is to get the list option from the database. Is there anybody who already solved this problem??

parisek’s picture

Skydda’s picture

How do I create list field, where users can input their own values?

kurtismccartney’s picture

Any luck finding a simple UL Field with add more function?’s picture

I have a need to create a field of custom "dynamic" check boxes type. In Drupal 6 I was able to create this with inserting php code in field definition. Is there a similar capability in Drupal 7.

Even though I am able to insert php code in node body and block body (after enabling PHP Filter in Drupal core), I was expecting to do the same in creating a field in custom content type.

As I didn't see this feature right away, I started customizing the code I found under examples/field_example. Is this the way to go or is there a better way to do it.

qstyler’s picture

Is there any chance I can use optgroups in this module?
Thank you!

calculus’s picture

Is there a way to add options to a list field, after content (that use it) has created? For example in list below:


Can i add 3|black ?

langweer’s picture

My experiences say that you can still change the list even if content has been created. There is the warning, that it can't be done, but if you just do it, the system doesn't give an error.
BUT: I can not promise that this is the right way to do (although it works for me).

2dareis2do’s picture

Not sure if this is the best place to post this but I am experiencing a problem with the list module.

I have a integer select list with the following key|value(s)


When I edit the node in my custom content type, I can select the value sand they seem to save, however when I go to edit the form again, my previously selected values have disappeared and I have to enter them again.

Please help, what am I doing wrong? How do I keep my selected values I have over 20 integer select lists on a form and don't want to have to re-enter everytime I make a minor change to a node.

BTW, list using a float instead of integer seems to work fine.

hbowie’s picture

I had the same problem: assigned integer list values were being reset when I went to edit a node, and the plain integer keys were being displayed instead of the label values.

I finally realized that the problem was apparently being caused by the leading zeroes I had entered for the single-digit values, as in the example above.

When I created a new integer list field, and dropped the leading zeroes, everything seemed to work fine.

Stomper’s picture

How does one remove or turn off the N/A option in a checkbox or radio list (text)?

rodrigo21’s picture

How does one remove or turn off the N/A option in a checkbox or radio list (text)?

Sustainable Transport in Drupal.

Stomper’s picture

Thanks. I figured it out. You just need to make the number of possible choices match the number of options.

gigab’s picture

Hi, how can i write "iframe" on Label?

gauravjeet’s picture

Use hook_form_alter, that simple :)..

- GJ

sethmac’s picture

I am really struggling to check a checkbox when creating a node using the following structure. Would love any insight..thanks!:

function mymodule_install() {
$node = new stdClass();
$node->type = 'group';
$node->title = 'MY AWESOME GROUP';
$node->language = LANGUAGE_NONE;

$node->group_group[$node->language] = array(0 => array('value' => 1));
$node->group_access[$node->language] = array(0 => array('value' => 1));
$node->field_list_one[$node->language] = array(0 => array('value' => 'AAA'));

$node->promote = 0;
$node->status = 1;
$node->uid = $user->uid;