Using Gravity Forms ‘gform_us_states’ PHP filter

The gform_us_states filter can be used to modify the choices listed in the US states drop-down in Gravity Forms.


add_filter('gform_us_states', 'your_function_name');


  • $states (array): The array to be filtered, containing the list of states in a standard array (e.g., array( 'Alabama', 'Alaska', 'Arizona', 'Arkansas', 'California', ... )).

More information

See Gravity Forms Docs: gform_us_states


Use State Code

Replace the state name with its two-letter code as the choice value.

add_filter('gform_us_states', 'us_states');

function us_states($states) {
    $new_states = array();
    foreach ($states as $state) {
        $new_states[GF_Fields::get('address')->get_us_state_code($state)] = $state;
    return $new_states;

Remove States

Remove specific states from the drop-down.

add_filter('gform_us_states', 'filter_us_states');

function filter_us_states($states) {
    $omit_states = array('Alaska', 'Hawaii');

    foreach ($states as $key => $state) {
        if (in_array($state, $omit_states)) {
    return $states;

Add Outlying Territories to US State List

Add US outlying territories to the state list.

add_filter('gform_us_states', 'us_states');

function us_states($states) {
    $territories = array(
        2 => 'American Samoa',
        12 => 'Guam',
        37 => 'Northern Mariana Islands',
        42 => 'Puerto Rico',
        59 => 'US Virgin Islands'
    return array_replace($states, $territories);

Sort States Alphabetically

Sort the state list alphabetically.

add_filter('gform_us_states', 'sort_us_states');

function sort_us_states($states) {
    return $states;

Add Custom State

Add a custom state to the drop-down.

add_filter('gform_us_states', 'add_custom_state');

function add_custom_state($states) {
    $states['Custom State'] = 'Custom State';
    return $states;