Table of Contents
stateRegion - Automatically group states or other geographic areas into regions
This function automatically assigns a region based on state (or province, area, etc.) selection from a searchable drop-down.
Functionality includes:
- Flexible assignment of states and regions to support any country
- Produces highly usable response data
- Searchable state drop-down
- Supports using either a single Side-by-Side question or a series of Multiple Choice questions
- Optionally records state abbreviation
- Optional state selection based on IP location
This function is available for a reasonable fee. Contact TomG on the Qualtrics Community to learn more.
Set-up Instructions
Survey Header
Add the select2 stylesheet and JS to the survey header. Go to Look & Feel → General → Header edit → and paste the html from jsdelivr:
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/select2@4.0.13/dist/css/select2.min.css"> <script src="https://cdn.jsdelivr.net/npm/select2@4.0.13/dist/js/select2.full.min.js"></script>
stateRegion function
The stateRegion function must also be added to the survey header. This will make the function available to any question in the survey. Go to Look & Feel → General → Header edit → and paste the provided stateRegion function JS:
<script>/*Paste stateRegion function JS here*/</script>
Alternatively, paste the stateRegion function JS into a question's JS outside the existing Qualtrics functions to make it available to questions on the page.
Custom CSS
CSS styles control the look of the state drop-down. Go to Look & Feel → General → Custom CSS edit and add the provided CSS rules.
Side-by-Side Question
The advantages of using a Side-by-side question is that the question is self-contained and you can co-exist with any number of other questions on the page.
The Side-by-side question will have one row and either 3 or 4 columns depending on whether state abbreviations are included. The first column is a drop-down with delimited states/regions as choices. The choices are either in the format state|region (e.g., Alabama|South) or state|abbreviation|region (e.g., Alabama|AL|South). The second column is a drop-down with the regions as choices. The region names must match the region names used in the first column. The third column is a text entry field for the state name. The fourth column is a text entry field for the state abbreviation and is only needed if the delimited choices in the first column include abbreviation. It will look something like this in the Qualtrics editor:
Series of Questions
As an alternative to a Side-by-side question, a series of 3 or 4 separate questions may be used. The series of questions must the last questions on the page. The first question must be a drop-down with delimited states/regions as choices. The choices are either in the format state|region (e.g., Alabama|South) or state|abbreviation|region (e.g., Alabama|AL|South). The second question is a drop-down with the regions as choices. The region names must match the region names used in the first question. The third question is a text entry question for the state name. The fourth question is a text entry question for the state abbreviation and is only needed if the delimited choices in the first question include abbreviation.
The advantages of using a series of questions are that the drop downs are easier to configure, and if it happens to be a screening question, it enables generation of test responses with Q_PopulateResponse (due to a bug in Generate Test Responses Side-by-side questions don't work properly when the answer is specified with Q_PopulateResponse)
JavaScript Function Call
Add JS to either the Side-by-Side question or the Drop-down question with the delimited states/regions as choices as follows:
Qualtrics.SurveyEngine.addOnReady(function() { stateRegion(this); });
To override the default options, specify the desired options in the second function argument as an object. For example:
Qualtrics.SurveyEngine.addOnReady(function() { stateRegion(this,{ipLoc:true}); });
Options
ddWidth
The width of the state input field.
Default: "auto"
debug
For testing purposes, debug can be set to true to see the Qualtrics question fields being captured.
Default: false
dropdownAutoWidth
Boolean to automatically set the width of the drop-down choices.
Default: true
ipLoc
Boolean to automatically select the lookup field (i.e., state) based on IP location.
Default: false
ipLocName
The name of the ip location field for the lookup field (i.e., state) when ipLoc is true. Valid values are "region" (state, province, etc.), "region_code", "city", "country_name", and "country_code".
Default: "region"
placeholder
Placeholder text to show before state is selected.
Default: "select or type state"
Question Text HTML
The side-by-side question or the first drop-down question with the delimited state/region choices must have the following html as the question text. Click on the Question Text and click the HTML View tab. ONLY edit the stateRegion question in HTML View. Qualtrics will make unexpected changes to question HTML when edited in other modes.
In which state do you currently live? <div style="padding-top:1em"><input class="state" type="text"></div> <style>.Skin {opacity:0;}</style>