Joomla list Form Field Type

The list form field type provides a drop down list or a list box of custom-defined entries. If the field has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.

The XML <field> element must include one or more <option> elements which define the list items. The text between the <option> and </option> tags is what will be shown in the drop down list and is a translatable string. The value argument of the <option> tag is the value that will be saved for the field if this item is selected. Don't forget to close the field definition with </field>.

XML Field Definition

<field 
name="mylistvalue"
type="list"
default=""
label="Select an option">
<option value="0">Option 1</option>
<option value="1">Option 2</option>
</field>

Add first an option without a value, with a text like "Select an option". Otherwise, in case of a required field, the first option with a value gets silently selected (without the user choosing it). This text will typically be seen by users before clicking the drop down list.

Additional Parameters

multiple: It defines whether multiple items can be selected at the same time (true or false).

header: (translatable) This is the first option that doesn't have any value. For example: JSELECT

useglobal: if set to true, it will show the value that is set in the global configuration if found in the database.

layout: Use "list-fancy-select" layout to provide search option in the drop down list.

  • joomla.form.field.list (Default)
  • joomla.form.field.list-fancy-select

onchange: The onchange event that occurs when the value is changed.

Examples

1. Display Offline Message (Global Configuration)

<field
name="display_offline_message"
type="list"
label="COM_CONFIG_FIELD_SITE_DISPLAY_MESSAGE_LABEL"
default="1"
filter="integer"
showon="offline:1"
validate="options">
<option value="0">JHIDE</option>
<option value="1">COM_CONFIG_FIELD_VALUE_DISPLAY_OFFLINE_MESSAGE_CUSTOM</option>
<option value="2">COM_CONFIG_FIELD_VALUE_DISPLAY_OFFLINE_MESSAGE_LANGUAGE</option>
</field>

2. State Field (com_content)

<field
name="state"
type="list"
label="JSTATUS"
class="form-select-color-state"
default="1"
validate="options">
<option value="1">JPUBLISHED</option>
<option value="0">JUNPUBLISHED</option>
<option value="2">JARCHIVED</option>
<option value="-2">JTRASHED</option>
</field>

3. Show Title Field (com_content)

<field
name="show_title"
type="list"
label="JGLOBAL_SHOW_TITLE_LABEL"
useglobal="true"
validate="options">
<option value="1">JSHOW</option>
<option value="0">JHIDE</option>
</field>