Organising your data

Creating Custom Fields

This chapter explains how you can collect information beyond that which CiviCRM allows by default through adding custom fields to hold the data you want to collect.

For example, you could add a set of checkboxes to organisations so that you could track the clients that they serve. You can also restrict custom fields to certain types of that object. For example, if you have a contact type Student, you might have a custom field listing the subjects they study.

Custom data fields are always stored as sets of custom fields in CiviCRM.  Therefore, adding custom data is a two-stage process:

  1. Create a custom field set, which is simply like a container to hold these custom fields together.
  2. Add custom fields to this set. (You may find it helpful to read the information about custom fields first, but you will need to create the field set before you create the fields in it). 

To clarify, a field is a unit of information entered into the database, such as someone's primary spoken language, or high school graduation date. A custom field set is a group of fields containing related data - that is, a set of fields related to a certain activity type, to participation in events, or to contributions.

Custom field sets

Custom fields are always part of custom field sets, and each set has a scope as wide or as narrow as you choose. For instance, you might associate a custom field set called "nationality" with all contact types, another set such as "immigration status" with a specific contact type (e.g. Individuals), and yet another set with a specific component (CiviMember, CiviEvent), or with other elements such as Relationships and Groups. The scope of a custom field set is one of the few decisions that is irreversible (you will not be able to change it after creating it) so it is important to consider carefully what you want to associate your custom field set with when you start.

When creating custom field sets, you should ask:

Taking the time to think through these questions helps keep your application screens as relevant and clear of superfluous fields as possible. For example, if your custom field set contains contact characteristics such as a field for the "color of eyes", you should associate them with the Individual contact type rather than the generic Contacts option, as this field would be irrelevant to Organization and Household contact types. Another example would be if custom data is specific to a particular event registration page. You should create this custom data for an Event type Participant for the specific Event.

Depending on how many custom fields you are creating, you should also consider grouping the fields topically. For example, you may associate 20 custom fields with Individual contacts, 12 of which relate to an online membership directory. Rather than group all 20 fields in a single custom field set, you may want to split them into two sets - one for the directory-related fields, and a second for more general Individual details.

To create a custom field set and custom fields, go to: Administer > Customize Data and Scrreens > Custom Data. This screen lets you assign a title to the field set, specify what type of records it will be used for, select the display characteristics, and enter help text. The form appears in the following image, and we'll describe each field.


Set Name

For custom field sets which are displayed inline, this name appears as the legend of the field set. If this set uses the tab display style, the name appears as the navigation tab label.

Used For

You can use this option to ensure that the fields appear only where they are relevant. The choices are:


This controls the order in which your custom field sets are presented when you have created more than one set. Lower numbers (e.g. 1, 2) are displayed above higher numbers (e.g. 8, 9).

Multiple records

Each field usually contains a single option. For example, a person has either blue eyes or brown eyes, not both. However, some fields are more complex and may require multiple entries, such as a person's educational history. A single person may have multiple educational degrees, so a custom field set about educational history should allow multiple records.

CiviCRM provides this functionality for custom field sets assigned to contacts (whether to all contact types or to a specific type). To use this option, select the "Does this Custom Field Set allow multiple records?" option. This option has several restrictions:

Display style

Custom field sets for Contact records are displayed either "inline" on the contact summary page (the Summary tab), or as a new tab at the top of the contact record, along with Summary, Contribution, Group, Note, etc. We suggest using tab display for infrequently accessed fields and large sets of fields.

Custom field sets used for components, relationships, or other resources are always displayed inline. Also note that custom field sets configured to handle multiple records will be displayed in the Summary tab.

Is this Custom Field Set active?

If a custom field set is active, its fields can be viewed and changed. Otherwise, the fields are in the CiviCVRM system but hidden from the user interface. This option can be valuable for managing your data, especially if you are migrating from an existing database system.

For example, your existing database may have fields you would like to transfer to CiviCRM for historical data keeping purposes, but plan to then deprecate or migrate to a new data structure. Suppose you are importing membership records from an MS Access database. Each record in Access has a unique ID (key) field, which has no direct benefit in CiviCRM. Rather than ignoring it altogether, you could create a custom field to hold the value, import the records, and then disable the field (keep the Activate option unchecked), thereby hiding it from view and minimising the interface clutter.

Though not visible to users, the field value is stored in the system and can be referenced at a later date. For instance, if you ever need to investigate archived data for a possible discrepancy or compare the field value with a printed record.

Individual fields can be made inactive in the form defining those fields, once the custom field set is active.

Pre-form Help and Post-form Help

If you enter text in Pre-form Help, your help text appears above the form field, and if you enter text in Post-form Help it appears below the form field. Use help at this level to provide instructions related to the entire set of custom fields.

Other settings

You can specify that you want the custom field set to be "collapsed" on initial display. If you check this box, only the title for this field set is displayed when the page is initially loaded, because the fields are hidden. This is helpful for field sets that are infrequently used because it reduces the screen real estate taken up when the page opens. A similar "collapsed" property is available for the display of custom data in Advanced Search.

Custom fields

Once you have created a custom field set, you can create custom data fields within the set. Click "View and Edit Custom Fields" followed by "New Custom Field" and you will see the screen in the image below. We'll explain each of the options in this section.

After completing the field configuration options, click 'Save' to record the field and return to the field listing for your current custom field set, or click 'Save and New' to save the field and begin defining a new field. You can view a listing of all the custom fields in a custom field set at any time by navigating to Administer > Customize > Custom Data and clicking 'View and Edit Custom Fields'.

With the exception of the data and input field type selection, all of the configuration options may be modified after your initial creation of the field. You may also find it useful to preview your custom fields, as well as the whole set of custom fields, as you are defining them. This is particularly useful for checking the layout of radio button and check-box fields with a large number of choices.


Field label

The text next to the field when displayed to the user. Text entered here is also the label shown when you export data. When using fields in a profile, you can overwrite the Field Label. So on this screen you can choose names that are suitable for administrators, and give more user-friendly names when exposing them in profiles.


Custom fields can be of many different types, many of which you've probably encountered when filling out forms on websites. When you create a custom field, CiviCRM presents a dropdown list of data types from which you can select that which best represents the data you plan to store. The menu on the left (shown open in the following figure) indicates the format of data you wish to store, whereas the menu on the right indicates the way you want to interact with the user.


The types of fields are:

We suggest you experiment with creating different field types to get an idea of how they behave. Different options have implications for use. For example, check-boxes enable you to use OR as well as AND searches in Advanced Search, whereas multi-select will not.

Database Field Length

The database field length allows you to specify the number of characters that this field will contain.  You should normally leave this at the maximum.  In certain cases (for example if you are dealing with extremely large field sets) it might make sense to shorten this field to improve performance and decrease storage space, but setting a shorter length will not make a difference to the vast majority of users.


Controls the order in which the fields appear. You may assign the order in the field edit form, or use the up/down icons on the main field listing table to adjust the field presentation. By default, new fields appear at the bottom of the field list within a set.

Default Value

Where applicable, you may designate a default value for a field. This value is automatically displayed or selected when users go to a form containing this field.

Pre-form Help and Post-form Help

Ideally, your field name is self-explanatory and users will immediately know what to enter. But in those cases where there is some ambiguity, or where you wish to help regulate how a certain field is used, you may enter help text here. If you enter it in Pre-form Help, your help text appears above the form field, and if you enter text in Post-form Help it appears below the form field.

The help text appears in all uses of the field in administration pages and is inserted as the default help text when fields are assigned to a profile (see 'profiles'). The person creating the profile can remove or change the help text there without impact on the original custom field definition.


When selected, a value must be provided for this field before the form can be submitted. Failure to do so will result in an error message directing the person to complete the required fields.

If you want a field to be required only when a user fills out a particular profile, you can leave this box unchecked and check the Required field later within the profile.

Is this Field Searchable?

Makes the field appear in a panel of custom fields in CiviCRM's Advanced Search page. While you may be tempted to mark every field as searchable, doing so may unnecessarily clutter the Advanced Search custom field panel, when in fact certain fields will probably never be used in that way. You may toggle this option on or off at any time, so do not be overly concerned about arriving at a final decision when you first define a custom field.


As with the active check-box in the form defining the custom field set, this box determines whether the field is disabled or enabled when CiviCRM displays it to the user.

View Only

This allows you to designate a field as visible but uneditable. There are two general uses for this field:

Multiple choice options

For field types that involve selecting from a set of multiple options (such as Select, Radio, Check-box, Multi-select and Advanced Multi-select) you are given the choice of either using an existing set of options that you've already created for another custom field or create a new set. You can enter these values while creating the field, or enter the values later. The option's label is displayed on the form, while the option's value is stored in the contact record.

If you choose to use the same set of options for several fields, you will be notified when making any changes that this will affect an option set used by several fields.

When you create a new set, you have the option of initially entering up to ten multiple choice options in a table. If you need more than ten options, you can create an unlimited number of additional choices after saving this new field by using the 'Edit Multiple Choice Options' link. Go to: Administer > Customize > Custom Data > View and Edit Custom Fields > Edit Multiple Choice Options. You may go to this screen at a later date to modify the label, order and active status of any multiple choice option, or add more choices. 


If desired, you can also mark one of the choices as the default option.

Inactive options are hidden when the field is presented.

Choosing between fields, groups and tags

Data fields, groups and tags are three major ways to associate information with contacts. Although it can be tempting to create a custom data field for every attribute of your data, take time to learn about the alternatives. They offer powerful functionality that you may miss out on if you rely only on custom data. Furthermore, using data fields for information where they could be stored more appropriately as groups or tags can slow your system. Finally, proper use of groups and tags makes it much easier for administrative staff to maintain the records.

Some tips that may help you choose are:

Custom field set limitations

Bear the following in mind when creating custom fields: 

  • Limit the number of custom fields in a set to fewer than 40. If you have approached this total, we recommend you import some records and test operations like search and export before finalizing your database design and putting it into production.

Why? CiviCRM stores each custom field set as a MySQL table with a column for each custom field in that set. It is important to consider this as you plan your custom data 'schema', as it will have the same advantages and limitations as other MySQL tables. If you put too many fields in one set, you risk exceeding MySQL's limit for maximum row-size, which may present search and data export issues later on (creating more than 40 custom data sets may result in exceeding MySQL's maximum allowed number of left joins - 64 - when performing operations like exporting data). Consult the MySQL Reference Manual for more details.

Download this book

Get involved

CiviCRM documentation is community driven. You can help improve documentation.

Powered by Flossmanuals.