State allows elements to trigger actions on a server

Activate Elements Programmatically

State is designed to make the process of integrating data sources to UI components seamless, tying State request state to UI states automatically.

For example adding an State behavior to an input will occur oninput, while a button, will query the server onclick.

Click Me


All the following behaviors can be called using the syntax:

$('.your.element') .state('behavior name', argumentOne, argumentTwo) ;
Behavior Description
query Execute query using existing State settings
add url data(url, data) Adds data to existing templated url and returns full url string
get request Gets promise for current State request
abort Aborts current State request
reset Removes loading and error state from element
was cancelled Returns whether last request was cancelled
was failure Returns whether last request was failure
was successful Returns whether last request was successful
was complete Returns whether last request was completed
is disabled Returns whether element is disabled
is mocked Returns whether element response is mocked
is loading Returns whether element is loading
set loading Sets loading state to element
set error Sets error state to element
remove loading Removes loading state to element
remove error Removes error state to element
get event Gets event that State request will occur on
get url encoded value(value) Returns encodeURIComponent value only if value passed is not already encoded
read cached response(url) Reads a locally cached response for a URL
write cached response(url, response) Writes a cached response for a URL
create cache Creates new cache, removing all locally cached URLs
destroy Removes State settings from the page and all events



Default Description
automatic true Whether possible states should be determined automatically based on type of UI
sync false When set to true and state is used on multiple elements, state will be synced across all bound elements.
flashDuration 1000 Default duration to show text when using flash text.
context false When set to a selector, will use a delegated pattern to bind events from this element.

Request Settings

Default Description Possible Values
action false Named State action for query, originally specified in $.fn.settings.state String or false
url false Templated URL for query, will override specified action String or false
urlData false Variables to use for replacement
mockResponse false Can be set to a javascript object which will be returned automatically instead of requesting JSON from server {} or false
mockResponseAsync(settings, callback) false When specified, this function can be used to retrieve content from a server and return it asynchronously instead of a standard AJAX call. The callback function should return the server response. function or false
method get Method for transmitting request to server post, get
dataType JSON Expected data type of response xml, json, jsonp, script, html, text
data {} POST/GET Data to Send with Request


Context Description
beforeSend(settings) initialized element Allows modifying settings before request, or cancelling request
beforeXHR(xhrObject) Allows modifying XHR object for request
onRequest(promise, xhr) state context Callback that occurs when request is made. Receives both the state success promise and the xhr request promise.
onResponse(response) state context Allows modifying the server's response before parsed by other callbacks to determine State event success
successTest(response) Determines whether completed JSON response should be treated as successful
onSuccess(response, element, xhr) state context Callback after successful response, JSON response must pass successTest
onComplete(response, element, xhr) state context Callback on request complete regardless of conditions
onFailure(response, element) state context Callback on failed response, or JSON response that fails successTest
onError(errorMessage, element, xhr) state context Callback on server error from returned status code, or XHR failure.
onAbort(errorMessage, element, xhr) state context Callback on abort caused by user clicking a link or manually cancelling request.


These settings are native to all modules, and define how the component ties content to DOM attributes, and debugging settings for the module.

Default Description
name State Name used in log statements
namespace state Event namespace. Makes sure module teardown does not effect other events attached to an element.
regExp : { required: /\{\$*[A-z0-9]+\}/g, optional: /\{\/\$*[A-z0-9]+\}/g, }
Regular expressions used for template matching
selector: { text : false }
Selectors used to find parts of a module
className: { active : 'active', disabled : 'disabled', error : 'error', loading : 'loading', success : 'success', warning : 'warning' }
Class names used to determine element state
metadata: { promise : 'promise', storedText : 'stored-text' }
Metadata used to store xhr and response promise
silent false Silences all console output including error messages, regardless of other debug settings.
debug false Debug output to console
performance true Show console.table output with performance metrics
verbose false Debug output includes all internal behaviors
// errors error : { method : 'The method you called is not defined.' }

Dimmer Message
Dimmer sub-header