Ext.form.field.Tag xtype: tagfield

store : Ext.data.Store / String / Array / Object

bindable bind required req

The data source to which the combo / tagfield is bound. Acceptable values for this property are:

• any Ext.data.Store class / subclass
• an ID of a store

• an Array : Arrays will be converted to a Ext.data.Store internally, automatically generating field names to work with all data components.

  • 1-dimensional array : (e.g., ['Foo','Bar'])

    A 1-dimensional array will automatically be expanded (each array item will be used for both the combo valueField and displayField)

  • 2-dimensional array : (e.g., [['f','Foo'],['b','Bar']])

    For a multi-dimensional array, the value in index 0 of each item will be assumed to be the combo valueField, while the value at index 1 is assumed to be the combo displayField.

• a Ext.data.Store config object. When passing a config you can specify the store type by alias. Passing a config object with a store type will dynamically create a new store of that type when the combo / tagfield is instantiated.

  Ext.define('MyApp.store.States', {

  extend: 'Ext.data.Store',
  alias: 'store.states',
  fields: ['name']
  

  });

  Ext.create({

  xtype: 'combobox',
  renderTo: document.body,
  store: {
      type: 'states',
      data: [{
          name: 'California'
      }]
  },
  queryMode: 'local',
  displayField: 'name',
  valueField: 'name'
  

  });

See also queryMode.

valueField : String

required req

The underlying data value name to bind to this ComboBox.

Note: use of a valueField requires the user to make a selection in order for a value to be mapped. See also displayField.

Defaults to match the value of the displayField config.

activeError : String

bindable bind

If specified, then the component will be displayed with this value as its active error when first rendered. Use setActiveError or unsetActiveError to change it after component creation.

activeErrorsTpl : String / String[] / Ext.XTemplate

The template used to format the Array of error messages passed to setActiveErrors into a single HTML string. if the msgTarget is title, it defaults to a list separated by new lines. Otherwise, it renders each message as an item in an unordered list.

Defaults to:

undefined

afterBodyEl : String / Array / Ext.XTemplate

An optional string or XTemplate configuration to insert in the field markup at the end of the input containing element. If an XTemplate is used, the component's render data serves as the context.

afterLabelTextTpl : String / Array / Ext.XTemplate

An optional string or XTemplate configuration to insert in the field markup after the label text. If an XTemplate is used, the component's render data serves as the context.

afterLabelTpl : String / Array / Ext.XTemplate

An optional string or XTemplate configuration to insert in the field markup after the label element. If an XTemplate is used, the component's render data serves as the context.

afterSubTpl : String / Array / Ext.XTemplate

An optional string or XTemplate configuration to insert in the field markup after the subTpl markup. If an XTemplate is used, the component's render data serves as the context.

alignOnScroll : Boolean

By default, when the alignTo method is called, a floating component will scroll to keep aligned with the anchoring element if the anchoring element is part of the scroll.

If this is not necessary, and the alignTo is a one-off operation then set this config to false.

Defaults to:

true

alignTarget : String

A Component or Element by which to position this component according to the defaultAlign. Defaults to the owning Container.

Only applicable if this component is cfg-floating

Used upon first show.

Defaults to:

null

allowBlank : Boolean

Specify false to validate that the value's length must be > 0. If true, then a blank value is always taken to be valid regardless of any vtype validation that may be applied.

If vtype validation must still be applied to blank values, configure validateBlank as true;

Defaults to:

true

allQuery : String

The text query to send to the server to return all records for the list with no filtering

Defaults to:

''

alwaysOnTop : Boolean / Number

bindable bind

A flag indicating that this component should be on the top of the z-index stack for use by the zIndexManager to sort its stack.

This may be a positive number to prioritize the ordering of multiple visible always on top components.

This may be set to a negative number to prioritize a component to the bottom of the z-index stack.

Defaults to:

false

anchor : String

This configuration option is to be applied to child items of a container managed by an Ext.layout.container.Anchor.

This value is what tells the layout how an item should be anchored to the container. items added to an AnchorLayout accept an anchoring-specific config property of anchor which is a string containing two values: the horizontal anchor value and the vertical anchor value (for example, '100% 50%'). The following types of anchor values are supported:

• Percentage : Any value between 1 and 100, expressed as a percentage.

  The first anchor is the percentage width that the item should take up within the container, and the second is the percentage height. For example:

  // two values specified
  anchor: '100% 50%' // render item complete width of the container and
                     // 1/2 height of the container
  // one value specified
  anchor: '100%'     // the width value; the height will default to auto
  

• Offsets : Any positive or negative integer value.

  This is a raw adjustment where the first anchor is the offset from the right edge of the container, and the second is the offset from the bottom edge. For example:

  // two values specified
  anchor: '-50 -100' // render item the complete width of the container
                     // minus 50 pixels and
                     // the complete height minus 100 pixels.
  // one value specified
  anchor: '-50'      // anchor value is assumed to be the right offset value
                     // bottom offset will default to 0
  

• Sides : Valid values are right (or r) and bottom (or b).

  Either the container must have a fixed size or an anchorSize config value defined at render time in order for these to have any effect.

• Mixed :

  Anchor values can also be mixed as needed. For example, to render the width offset from the container right edge by 50 pixels and 75% of the container's height use:

  anchor:   '-50 75%'
  

animateShadow : Boolean

true to animate the shadow along with the component while the component is animating. By default the shadow is hidden while the component is animating

Defaults to:

false

anyMatch : Boolean

Configure as true to allow matching of the typed characters at any position in the valueField's value.

Defaults to:

false

ariaAttributes : Object

bindable bind

An object containing ARIA attributes to be set on this Component's ARIA element. Use this to set the attributes that cannot be determined by the Component's state, such as aria-live, aria-flowto, etc.

Note that this config is only meaningful at the Component rendering time, and setting it after that will do nothing.

Defaults to:

null

ariaDescribedBy : String

DOM selector for a child element that is to be used as description for this Component, set in aria-describedby attribute. The selector works the same way as ariaLabelledBy.

ariaErrorText : String

Localized announcement text for validation errors. This text will be used by Assistive Technologies such as screen readers to alert the users when field validation fails.

This config is used with Ext.String#format. '{0}' will be replaced with the actual error message(s), '{1}' will be replaced with field label.

Defaults to:

'Input error. {0}.'

ariaHelp : String

Optional text description for this object. This text will be announced to Assistive Technology users when the object is focused.

Defaults to:

undefined

ariaLabel : String

ARIA label for this Component. It is best to use ariaLabelledBy option instead, because screen readers prefer aria-labelledby attribute to aria-label. ariaLabel and ariaLabelledBy config options are mutually exclusive.

ariaLabelledBy : String

DOM selector for a child element that is to be used as label for this Component, set in aria-labelledby attribute. If the selector is by id, the label element can be any existing element, not necessarily a child of the main Component element.

ariaLabelledBy and ariaLabel config options are mutually exclusive, and ariaLabelledBy has the higher precedence.

autoEl : String / Object

A tag name or Ext.dom.Helper spec used to create the Element which will encapsulate this Component.

You do not normally need to specify this. For the base classes Ext.Component and Ext.container.Container, this defaults to 'div'. The more complex Sencha classes use a more complex DOM structure specified by their own cfg-renderTpls.

This is intended to allow the developer to create application-specific utility Components encapsulated by different DOM elements. Example usage:

{
    xtype: 'component',
    autoEl: {
        tag: 'img',
        src: 'http://www.example.com/example.jpg'
    }
}, {
    xtype: 'component',
    autoEl: {
        tag: 'blockquote',
        html: 'autoEl is cool!'
    }
}, {
    xtype: 'container',
    autoEl: 'ul',
    cls: 'ux-unordered-list',
    items: {
        xtype: 'component',
        autoEl: 'li',
        html: 'First list item'
    }
}

Available since: 2.3.0

autoFitErrors : Boolean

Whether to adjust the component's body width to make room for 'side' error messages.

Defaults to:

true

autoLoadOnValue : Boolean

This option controls whether to initially load the store when a value is set so that the display value can be determined from the appropriate record. The store will only be loaded in a limited set of circumstances:

• The store is not currently loading.
• The store does not have a pending Ext.data.Store#autoLoad.
• The store has not been loaded before.

Defaults to:

false

autoRender : Boolean / String / HTMLElement / Ext.dom.Element

This config is intended mainly for non-cfg-floating Components which may or may not be shown. Instead of using renderTo in the configuration, and rendering upon construction, this allows a Component to render itself upon first show. If cfg-floating is true, the value of this config is omitted as if it is true.

Specify as true to have this Component render to the document body upon first show.

Specify as an element, or the ID of an element to have this Component render to a specific element upon first show.

Defaults to:

false

autoSelect : Boolean

true to automatically highlight the first result gathered by the data store in the dropdown list when it is opened. A false value would cause nothing in the list to be highlighted automatically, so the user would have to manually highlight an item before pressing the enter or tab key to select it (unless the value of (typeAhead) were true), or use the mouse to select a value.

Defaults to:

true

autoSelectLast : Boolean

When true, the last selected record in the dropdown list will be re-selected upon autoSelect. Set to false to always select the first record in the drop-down list. For accessible applications it is recommended to set this option to false.

Defaults to:

true

autoShow : Boolean

true to automatically show the component upon creation. This config option may only be used for cfg-floating components or components that use autoRender.

Defaults to:

false

Available since: 2.3.0

baseBodyCls : String

The CSS class to be applied to the body content element.

Defaults to:

Ext.baseCSSPrefix + 'form-item-body'

baseCls : String

The base CSS class to apply to this component's element. This will also be prepended to elements within this component like Panel's body will get a class x-panel-body. This means that if you create a subclass of Panel, and you want it to get all the Panels styling for the element and the body, you leave the baseCls x-panel and use componentCls to add specific styling for this component.

Defaults to:

'x-component'

beforeBodyEl : String / Array / Ext.XTemplate

An optional string or XTemplate configuration to insert in the field markup at the beginning of the input containing element. If an XTemplate is used, the component's render data serves as the context.

beforeLabelTextTpl : String / Array / Ext.XTemplate

An optional string or XTemplate configuration to insert in the field markup before the label text. If an XTemplate is used, the component's render data serves as the context.

beforeLabelTpl : String / Array / Ext.XTemplate

An optional string or XTemplate configuration to insert in the field markup before the label element. If an XTemplate is used, the component's render data serves as the context.

beforeSubTpl : String / Array / Ext.XTemplate

An optional string or XTemplate configuration to insert in the field markup before the subTpl markup. If an XTemplate is used, the component's render data serves as the context.

bind : Object / String

bindable bind

Setting this config option adds or removes data bindings for other configs. For example, to bind the title config:

 var panel = Ext.create({
     xtype: 'panel',
     bind: {
         title: 'Hello {user.name}'
     }
 });

To dynamically add bindings:

 panel.setBind({
     title: 'Greetings {user.name}!'
 });

To remove bindings:

 panel.setBind({
     title: null
 });

The bind expressions are presented to Ext.app.ViewModel#bind. The ViewModel instance is determined by lookupViewModel.

Note: If bind is passed as a string, it will use the Ext.Component#property-defaultBindProperty for the binding.

Defaults to:

null

blankText : String

The error text to display if the allowBlank validation fails

Defaults to:

'This field is required'

border : Number / String / Boolean

bindable bind

Specifies the border size for this component. The border can be a single numeric value to apply to all sides or it can be a CSS style specification for each style, for example: '10 5 3 10' (top, right, bottom, left).

For components that have no border by default, setting this won't make the border appear by itself. You also need to specify border color and style:

border: 5,
style: {
    borderColor: 'red',
    borderStyle: 'solid'
}

To turn off the border, use border: false.

caseSensitive : Boolean

Configure as true to make the filtering match with exact case matching

Defaults to:

false

checkChangeBuffer : Number

Defines a timeout in milliseconds for buffering checkChangeEvents that fire in rapid succession. Defaults to 50 milliseconds.

Defaults to:

50

checkChangeEvents : String[]

A list of event names that will be listened for on the field's input element, which will cause the field's value to be checked for changes. If a change is detected, the change event will be fired, followed by validation if the validateOnChange option is enabled.

Defaults to ['change', 'propertychange', 'keyup'] in Internet Explorer, and ['change', 'input', 'textInput', 'keyup', 'dragdrop'] in other browsers. This catches all the ways that field values can be changed in most supported browsers; the only known exceptions at the time of writing are:

• Safari 3.2 and older: cut/paste in textareas via the context menu, and dragging text into textareas
• Opera 10 and 11: dragging text into text fields and textareas, and cut via the context menu in text fields and textareas
• Opera 9: Same as Opera 10 and 11, plus paste from context menu in text fields and textareas

If you need to guarantee on-the-fly change notifications including these edge cases, you can call the checkChange method on a repeating interval, e.g. using Ext.TaskManager, or if the field is within a Ext.form.Panel, you can use the FormPanel's Ext.form.Panel#pollForChanges configuration to set up such a task automatically.

Defaults to:

Ext.isIE && (!document.documentMode || document.documentMode <= 9) ? [
    'change',
    'propertychange',
    'keyup'
] : [
    'change',
    'input',
    'textInput',
    'keyup',
    'dragdrop'
]

childEls : Object / String[] / Object[]

bindable bind

The canonical form of childEls is an object keyed by child's property name with values that are objects with the following properties.

• itemId - The id to combine with the Component's id that is the id of the child element.
• id - The id of the child element.
• leaf - Set to true to ignore content when scanning for childEls. This should be set on things like the generated content for an Ext.view.View.
• select: A selector that will be passed to Ext.dom.Element#method-select.
• selectNode: A selector that will be passed to Ext.dom.Element#method-selectNode.

For example:

 childEls: {
     button: true,
     buttonText: 'text',
     buttonImage: {
         itemId: 'image'
     }
 }

The above is translated into the following complete form:

 childEls: {
     button: {
         name: 'button',
         itemId: 'button'
     },
     buttonText: {
         name: 'buttonText',
         itemId: 'text'
     },
     buttonImage: {
         name: 'buttonImage',
         itemId: 'image'
     }
 }

The above can be provided as an array like so:

 childEls: [
     'button',
     { name: 'buttonText', itemId: 'text' },
     { name: 'buttonImage', itemId: 'image' }
 }

For example, a Component which renders a title and body text:

Note: childEls in the renderTpl must be referenced in a data-ref attribute. Notice in the above example that the "title" childEl is set in the renderTpl using data-ref="title".

When using select, the property will be an instance of Ext.CompositeElement. In all other cases, the property will be an Ext.dom.Element or null if not found.

Care should be taken when using select or selectNode to find child elements. The following issues should be considered:

• Performance: using selectors can be 10x slower than id lookup.
• Over-selecting: selectors are applied after the DOM elements for all children have been rendered, so selectors can match elements from child components (including nested versions of the same component) accidentally.

This above issues are most important when using select since it returns multiple elements.

Defaults to:

{
    frameTable: {
        frame: true
    },
    frameTL: {
        frame: 'tl'
    },
    frameTC: {
        frame: 'tc'
    },
    frameTR: {
        frame: 'tr'
    },
    frameML: {
        frame: 'ml'
    },
    frameBody: {
        frame: 'mc'
    },
    frameMR: {
        frame: 'mr'
    },
    frameBL: {
        frame: 'bl'
    },
    frameBC: {
        frame: 'bc'
    },
    frameBR: {
        frame: 'br'
    }
}

clearFilterOnBlur : Boolean

When queryMode is 'local' only

As text is entered, the underlying store is filtered to match the value. When this option is true, any filtering applied by this field will be cleared when focus is removed & reinstated on focus. If false, the filters will be left in place.

Defaults to:

true

cls : String / String[]

An optional extra CSS class that will be added to this component's Element. The value can be a string, a list of strings separated by spaces, or an array of strings. This can be useful for adding customized styles to the component or any of its children using standard CSS rules.

Defaults to:

''

Available since: 1.1.0

columnWidth : Number

Defines the column width inside Ext.layout.container.Column.

The columnWidth property is always evaluated as a percentage and must be a decimal value greater than 0 and less than 1 (e.g., .25). See the description at the top of Ext.layout.container.Column for additional usage details when combining width and columnWidth configs within the layout.

componentCls : String

CSS Class to be added to a components root level element to give distinction to it via styling.

componentLayout : String / Object

bindable bind

The sizing and positioning of a Component's internal Elements is the responsibility of the Component's layout manager which sizes a Component's internal structure in response to the Component being sized.

Generally, developers will not use this configuration as all provided Components which need their internal elements sizing (Such as Ext.form.field.Base) come with their own componentLayout managers.

The Ext.layout.container.Auto will be used on instances of the base Ext.Component class which simply sizes the Component's encapsulating element to the height and width specified in the setSize method.

Defaults to:

'autocomponent'

constrain : Boolean

True to constrain this Components within its containing element, false to allow it to fall outside of its containing element. By default this Component will be rendered to document.body. To render and constrain this Component within another element specify renderTo.

Defaults to:

false

constraintInsets : Object / String

An object or a string (in TRBL order) specifying insets from the configured constrain region within which this component must be constrained when positioning or sizing. example:

constraintInsets: '10 10 10 10' // Constrain with 10px insets from parent

constrainTo : Ext.util.Region / Ext.dom.Element

A Ext.util.Region (or an element from which a Region measurement will be read) which is used to constrain the component. Only applies when the component is floating.

contentEl : String

Specify an existing HTML element, or the id of an existing HTML element to use as the content for this component.

This config option is used to take an existing HTML element and place it in the layout element of a new component (it simply moves the specified DOM element after the Component is rendered to use as the content.

Notes:

The specified HTML element is appended to the layout element of the component after any configured HTML has been inserted, and so the document will not contain this element at the time the event-render event is fired.

The specified HTML element used will not participate in any layout scheme that the Component may use. It is just HTML. Layouts operate on child items.

Add either the x-hidden or the x-hidden-display CSS class to prevent a brief flicker of the content before it is rendered to the panel.

Available since: 3.4.0

controller : String / Object / Ext.app.ViewController

bindable bind

A string alias, a configuration object or an instance of a ViewController for this container. Sample usage:

Ext.define('MyApp.UserController', {
    alias: 'controller.user'
});

Ext.define('UserContainer', {
    extend: 'Ext.container.container',
    controller: 'user'
});
// Or
Ext.define('UserContainer', {
    extend: 'Ext.container.container',
    controller: {
        type: 'user',
        someConfig: true
    }
});

// Can also instance at runtime
var ctrl = new MyApp.UserController();
var view = new UserContainer({
    controller: ctrl
});

Defaults to:

null

data : Object

bindable bind

The initial set of data to apply to the tpl to update the content area of the Component.

Defaults to:

null

Available since: 3.4.0

defaultAlign : String

The default Ext.dom.Element#getAlignToXY anchor position value for this component relative to its alignTarget (which defaults to its owning Container).

Only applicable if this component is cfg-floating

Used upon first show.

Defaults to:

"c-c"

defaultListConfig : Object

Set of options that will be used as defaults for the user-configured listConfig object.

Defaults to:

{
    loadingHeight: 70,
    minWidth: 70,
    maxHeight: 300,
    shadow: 'sides'
}

defaultListenerScope : Boolean

bindable bind

If true, this component will be the default scope (this pointer) for events specified with string names so that the scope can be dynamically resolved. The component will automatically become the defaultListenerScope if a controller is specified.

See the introductory docs for Ext.container.Container for some sample usages.

NOTE: This value can only be reliably set at construction time. Setting it after that time may not correctly rewire all of the potentially effected listeners.

Defaults to:

false

dirtyCls : String

The CSS class to use when the field value is dirty.

Defaults to:

Ext.baseCSSPrefix + 'form-dirty'

disabled : Boolean

bindable bind

true to disable the component.

Defaults to:

false

Available since: 2.3.0

disabledCls : String

CSS class to add when the Component is disabled.

Defaults to:

'x-item-disabled'

disableKeyFilter : Boolean

Specify true to disable input keystroke filtering. This will ignore the maskRe field.

Defaults to:

false

displayField : String

bindable bind

The underlying data field name to bind to this ComboBox.

See also valueField.

Defaults to:

'text'

displayTpl : String / String[] / Ext.XTemplate

bindable bind

The template to be used to display selected records inside the text field. An array of the selected records' data will be passed to the template. Defaults to:

'<tpl for=".">' +
    '{[typeof values === "string" ? values : values["' + me.displayField + '"]]}' +
    '<tpl if="xindex < xcount">' + me.delimiter + '</tpl>' +
'</tpl>'

By default only the immediate data of the record is passed (no associated data). The getRecordDisplayData can be overridden to extend this.

Defaults to:

null

dock : 'top' / 'bottom' / 'left' / 'right'

bindable bind

The side of the Ext.panel.Panel where this component is to be docked when specified in the panel's dockedItems config.

Possible values are:

• top
• bottom
• left
• right

draggable : Boolean / Object

Specify as true to make a cfg-floating Component draggable using the Component's encapsulating element as the drag handle.

This may also be specified as a config object for the Ext.util.ComponentDragger which is instantiated to perform dragging.

For example to create a Component which may only be dragged around using a certain internal element as the drag handle, use the delegate option:

new Ext.Component({
    constrain: true,
    floating: true,
    style: {
        backgroundColor: '#fff',
        border: '1px solid black'
    },
    html: '<h1 style="cursor:move">The title</h1><p>The content</p>',
    draggable: {
        delegate: 'h1'
    }
}).show();

Defaults to:

false

editable : Boolean

bindable bind

False to prevent the user from typing text directly into the field; the field can only have its value set via selecting a value from the picker. In this state, the picker can also be opened by clicking directly on the input field itself.

Defaults to:

true

emptyCls : String

The CSS class to apply to an empty field to style the emptyText. This class is automatically added and removed as needed depending on the current field value.

Defaults to:

'x-form-empty-field'

emptyText : String

bindable bind

The default text to place into an empty field.

Note that normally this value will be submitted to the server if this field is enabled; to prevent this you can set the submitEmptyText option of Ext.form.Basic#submit to false.

Also note that if you use inputType:'file', emptyText is not supported and should be avoided.

Note that for browsers that support it, setting this property will use the HTML 5 placeholder attribute, and for older browsers that don't support the HTML 5 placeholder attribute the value will be placed directly into the input element itself as the raw value. This means that older browsers will obfuscate the emptyText value for password input fields.

Defaults to:

''

enableKeyEvents : Boolean

true to enable the proxying of key events for the HTML input field

Defaults to:

false

enableRegEx : Boolean

When queryMode is 'local' only

Set to true to have the ComboBox use the typed value as a RegExp source to filter the store to get possible matches. Invalid regex values will be ignored.

enforceMaxLength : Boolean

True to set the maxLength property on the underlying input field. Defaults to false

errorMsgCls : String

The CSS class to be applied to the error message element.

Defaults to:

Ext.baseCSSPrefix + 'form-error-msg'

fieldBodyCls : String

An extra CSS class to be applied to the body content element in addition to baseBodyCls.

Defaults to:

''

fieldCls : String

The default CSS class for the field input

Defaults to:

'x-form-field'

fieldLabel : String

bindable bind

The label for the field. It gets appended with the labelSeparator, and its position and sizing is determined by the labelAlign and labelWidth configs.

Defaults to:

undefined

fieldStyle : String

bindable bind

Optional CSS style(s) to be applied to the field input element. Should be a valid argument to Ext.dom.Element#applyStyles. Defaults to undefined. See also the setFieldStyle method for changing the style after initialization.

fixed : Boolean

Configure as true to have this Component fixed at its X, Y coordinates in the browser viewport, immune to scrolling the document.

Defaults to:

false

flex : Number

bindable bind

Flex may be applied to child items of a box layout (Ext.layout.container.VBox or Ext.layout.container.HBox). Each child item with a flex property will fill space (horizontally in hbox, vertically in vbox) according to that item's relative flex value compared to the sum of all items with a flex value specified.

Any child items that have either a flex of 0 or undefined will not be 'flexed' (the initial size will not be changed).

floating : Boolean

Specify as true to float the Component outside of the document flow using CSS absolute positioning.

Components such as Ext.window.Windows and Ext.menu.Menus are floating by default.

Floating Components that are programmatically rendered will register themselves with the global Ext.WindowManager

Floating Components as child items of a Container

A floating Component may be used as a child item of a Container. This just allows the floating Component to seek a ZIndexManager by examining the ownerCt chain.

When configured as floating, Components acquire, at render time, a Ext.ZIndexManager which manages a stack of related floating Components. The ZIndexManager sorts its stack according to an incrementing access counter and the alwaysOnTop config when the Component's toFront method is called.

The ZIndexManager is found by traversing up the ownerCt chain to find an ancestor which itself is floating. This is so that descendant floating Components of floating Containers (Such as a ComboBox dropdown within a Window) can have its zIndex managed relative to any siblings, but always above that floating ancestor Container.

If no floating ancestor is found, a floating Component registers itself with the default Ext.WindowManager.

Floating components do not participate in the Container's layout. Because of this, they are not rendered until you explicitly method-show them.

After rendering, the ownerCt reference is deleted, and the floatParent property is set to the found floating ancestor Container. If no floating ancestor Container was found the floatParent property will not be set.

Defaults to:

false

focusCls : String

The CSS class to use when the field receives focus

Defaults to:

'x-form-focus'

focusOnToFront : Boolean

Specifies whether the floated component should be automatically focused when it is brought to the front.

Defaults to:

true

formatText : String

Helpful text describing acceptable format for field values. This text will be announced by Assistive Technologies such as screen readers when the field is focused.

This option is superseded by ariaHelp.

formBind : Boolean

When inside FormPanel, any component configured with formBind: true will be enabled/disabled depending on the validity state of the form. See Ext.form.Panel for more information and example.

Defaults to:

false

formItemCls : String

A CSS class to be applied to the outermost element to denote that it is participating in the form field layout.

Defaults to:

Ext.baseCSSPrefix + 'form-item'

frame : Boolean

Specify as true to have the Component inject framing elements within the Component at render time to provide a graphical rounded frame around the Component content.

This is only necessary when running on outdated, or non standard-compliant browsers such as Microsoft's Internet Explorer prior to version 9 which do not support rounded corners natively.

The extra space taken up by this framing is available from the read only property frameSize.

height : Number / String

bindable bind

The height of this component. A numeric value will be interpreted as the number of pixels; a string value will be treated as a CSS value with units.

hidden : Boolean

bindable bind

true to hide the component.

Defaults to:

false

Available since: 2.3.0

hiddenName : String

The name of an underlying hidden field which will be synchronized with the underlying value of the combo. This option is useful if the combo is part of a form element doing a regular form post. The hidden field will not be created unless a hiddenName is specified.

Defaults to:

""

hideEmptyLabel : Boolean

When set to true, the label element (fieldLabel and labelSeparator) will be automatically hidden if the fieldLabel is empty. Setting this to false will cause the empty label element to be rendered and space to be reserved for it; this is useful if you want a field without a label to line up with other labeled fields in the same form.

If you wish to unconditionall hide the label even if a non-empty fieldLabel is configured, then set the hideLabel config to true.

Defaults to:

true

hideLabel : Boolean

Set to true to completely hide the label element (fieldLabel and labelSeparator). Also see hideEmptyLabel, which controls whether space will be reserved for an empty fieldLabel.

Defaults to:

false

hideMode : String

A String which specifies how this Component's encapsulating DOM element will be hidden. Values may be:

• 'display' : The Component will be hidden using the display: none style.
• 'visibility' : The Component will be hidden using the visibility: hidden style.
• 'offsets' : The Component will be hidden by absolutely positioning it out of the visible area of the document. This is useful when a hidden Component must maintain measurable dimensions. Hiding using display results in a Component having zero dimensions.

Defaults to:

'display'

Available since: 1.1.0

hideTrigger : Boolean

bindable bind

true to hide all triggers

Defaults to:

false

html : String / Object

bindable bind

An HTML fragment, or a Ext.dom.Helper specification to use as the layout element content. The HTML content is added after the component is rendered, so the document will not contain this HTML at the time the event-render event is fired. This content is inserted into the body before any configured contentEl is appended.

Defaults to:

''

Available since: 3.4.0

id : String

The unique id of this component instance.

Use of this config should be considered carefully as this value must be unique across all existing components. Components created with an id may be accessed globally using Ext.getCmp.

Instead of using assigned ids, consider a reference config and a ViewController to respond to events and perform processing upon this Component.

Alternatively, itemId and Ext.ComponentQuery can be used to perform selector-based searching for Components analogous to DOM querying. The Ext.container.Container class contains several helpful shortcut methods to query its descendant Components by selector.

Note that this id will also be used as the element id for the containing HTML element that is rendered to the page for this component. This allows you to write id-based CSS rules to style the specific instance of this component uniquely, and also to select sub-elements using this component's id as the parent.

Defaults to an auto-assigned id.

Note: Valid identifiers start with a letter or underscore and are followed by (optional) additional letters, underscores, digits or hyphens.

Available since: 1.1.0

inputAttrTpl : String / Array / Ext.XTemplate

An optional string or XTemplate configuration to insert in the field markup inside the input element (as attributes). If an XTemplate is used, the component's subTpl data serves as the context.

inputId : String

The id that will be given to the generated input DOM element. Defaults to an automatically generated id. If you configure this manually, you must make sure it is unique in the document.

inputType : String

The type attribute for input fields -- e.g. radio, text, password, file. The extended types supported by HTML5 inputs (url, email, etc.) may also be used, though using them will cause older browsers to fall back to 'text'.

The type 'password' must be used to render that field type currently -- there is no separate Ext component for that. You can use Ext.form.field.File which creates a custom-rendered file upload field, but if you want a plain unstyled file input you can use a Base with inputType:'file'.

Defaults to:

'text'

inputWrapCls : String

The CSS class that is added to the element wrapping the input element

Defaults to:

Ext.baseCSSPrefix + 'form-text-wrap'

invalidCls : String

The CSS class to use when marking the component invalid.

Defaults to:

Ext.baseCSSPrefix + 'form-invalid'

invalidText : String

The error text to use when marking a field invalid and no message is provided

Defaults to:

'The value in this field is invalid'

itemId : String

The unique id of this component instance within its container. See also the reference config.

An itemId can be used as an alternative way to get a reference to a component when no object reference is available. Instead of using an id with getCmp, use itemId with getComponent which will retrieve itemId's or id's. Since itemId's are an index to the container's internal collection, the itemId is scoped locally to the container -- avoiding potential conflicts with Ext.ComponentManager, which requires a unique id value.

var c = new Ext.panel.Panel({ //
    height: 300,
    renderTo: document.body,
    layout: 'auto',
    items: [{
        itemId: 'p1',
        title: 'Panel 1',
        height: 150
    },{
        itemId: 'p2',
        title: 'Panel 2',
        height: 150
    }]
});

p1 = c.getComponent('p1'); // not the same as Ext.getCmp()
console.log(p1);
p2 = p1.ownerCt.getComponent('p2'); // reference via a sibling
console.log(p2);

Also see id, Ext.container.Container#query, Ext.container.Container#down and Ext.container.Container#child.

Note: Valid identifiers start with a letter or underscore and are followed by (optional) additional letters, underscores, digits or hyphens.

Note: to access the container of an item see ownerCt.

Available since: 3.4.0

keyMap : Object

bindable bind

An object containing handlers for keyboard events. The property names of this object are the key name and any modifiers. The values of the properties are the descriptors of how to handle each event.

The handler descriptor can be simply the handler function (either the literal function or the method name), or it can be an object with these properties:

• handler: The function or its name to call to handle the event.
• scope: The this pointer context (can be "this" or "controller").
• event: An optional override of the key event to which to listen.

Important: Calls to setKeyMap do not replace the entire keyMap but instead update the provided mappings. That is, unless null is passed as the value of the keyMap which will clear the keyMap of all entries.

Defaults to:

null

Properties

scope : String

The default scope to apply to key handlers which do not specify a scope. This is processed the same way as the scope of cfg-listeners. It defaults to the "controller", but using 'this' means that an instance method will be used.

keyMapEnabled : Boolean

bindable bind

Enables or disables processing keys in the keyMap. This value starts as null and if it is null when initKeyMap is called, it will automatically be set to true. Since initKeyMap is called by Ext.Component at the proper time, this is not something application code normally handles.

Defaults to:

null

labelAlign : String

Controls the position and alignment of the fieldLabel. Valid values are:

• "left" (the default) - The label is positioned to the left of the field, with its text aligned to the left. Its width is determined by the labelWidth config.
• "top" - The label is positioned above the field.
• "right" - The label is positioned to the left of the field, with its text aligned to the right. Its width is determined by the labelWidth config.

Defaults to:

'left'

labelAttrTpl : String / Array / Ext.XTemplate

An optional string or XTemplate configuration to insert in the field markup inside the label element (as attributes). If an XTemplate is used, the component's render data serves as the context.

labelCls : String

The CSS class to be applied to the label element. This (single) CSS class is used to formulate the renderSelector and drives the field layout where it is concatenated with a hyphen ('-') and labelAlign. To add additional classes, use labelClsExtra.

Defaults to:

Ext.baseCSSPrefix + 'form-item-label'

labelClsExtra : String

An optional string of one or more additional CSS classes to add to the label element. Defaults to empty.

labelPad : Number

The amount of space in pixels between the fieldLabel and the field body. This defaults to 5 for compatibility with Ext JS 4, however, as of Ext JS 5 the space between the label and the body can optionally be determined by the theme using the $form-label-horizontal-spacing (for side-aligned labels) and $form-label-vertical-spacing (for top-aligned labels) SASS variables. In order for the stylesheet values as to take effect, you must use a labelPad value of null.

Defaults to:

5

labelSeparator : String

Character(s) to be inserted at the end of the label text.

Set to empty string to hide the separator completely.

Defaults to:

':'

labelStyle : String

A CSS style specification string to apply directly to this field's label.

labelWidth : Number

The width of the fieldLabel in pixels. Only applicable if labelAlign is set to "left" or "right".

Defaults to:

100

liquidLayout : Boolean

Components that achieve their internal layout results using solely CSS with no JS intervention must set this to true. This allows the component to opt out of the layout run when used inside certain container layouts such as Ext.layout.container.Form and Ext.layout.container.Auto resulting in a performance gain. The following components currently use liquid layout (liquidLayout: true):

• All Form Fields (subclasses of Ext.form.field.Base)
• Ext.button.Button

It is important to keep in mind that components using liquidLayout do not fire the following events:

• event-resize
• event-boxready

In addition liquidLayout components do not call the following template methods:

• afterComponentLayout
• onBoxReady
• onResize

Any component that needs to fire these events or to have these methods called during its life cycle needs to set liquidLayout to false. The following example demonstrates how to enable the resize event for a Ext.form.field.TextArea:

Use caution when setting liquidLayout to false as it carries a performance penalty since it means the layout system must perform expensive DOM reads to determine the Component's size.

Defaults to:

false

listConfig : Object

An optional set of configuration properties that will be passed to the Ext.view.BoundList's constructor. Any configuration that is valid for BoundList can be included. Some of the more useful ones are:

• cls - defaults to empty
• emptyText - defaults to empty string
• itemSelector - defaults to the value defined in BoundList
• loadingText - defaults to 'Loading...'
• minWidth - defaults to 70
• maxWidth - defaults to undefined
• maxHeight - defaults to 300
• resizable - defaults to false
• shadow - defaults to 'sides'
• width - defaults to undefined (automatically set to the width of the ComboBox field if matchFieldWidth is true)

• getInnerTpl A function which returns a template string which renders the ComboBox's displayField value in the dropdown. This defaults to just outputting the raw value, but may use any Ext.XTemplate methods to produce output.

  The running template is configured with some extra properties that provide some context:

  - field Ext.form.field.ComboBox This combobox
  - store Ext.data.Store This combobox's data store
  

listeners : Object

bindable bind

A config object containing one or more event handlers to be added to this object during initialization. This should be a valid listeners config object as specified in the addListener example for attaching multiple handlers at once.

DOM events from Ext JS Ext.Component

While some Ext JS Component classes export selected DOM events (e.g. "click", "mouseover" etc), this is usually only done when extra value can be added. For example the Ext.view.View's itemclick event passing the node clicked on. To access DOM events directly from a child element of a Component, we need to specify the element option to identify the Component property to add a DOM listener to:

new Ext.panel.Panel({
    width: 400,
    height: 200,
    dockedItems: [{
        xtype: 'toolbar'
    }],
    listeners: {
        click: {
            element: 'el', //bind to the underlying el property on the panel
            fn: function(){ console.log('click el'); }
        },
        dblclick: {
            element: 'body', //bind to the underlying body property on the panel
            fn: function(){ console.log('dblclick body'); }
        }
    }
});

liveDrag : Boolean

True to drag the component itself. Else a lightweight version of the component will be shown (using the component's ghost() method).

Note: This config is only relevant when used with dragging implemented via Ext.util.ComponentDragger.

Defaults to:

false

loader : Ext.ComponentLoader / Object

A configuration object or an instance of a Ext.ComponentLoader to load remote content for this Component.

Ext.create('Ext.Component', {
    loader: {
        url: 'content.html',
        autoLoad: true
    },
    renderTo: Ext.getBody()
});

margin : Number / String

bindable bind

Specifies the margin for this component. The margin can be a single numeric value to apply to all sides or it can be a CSS style specification for each style, for example: '10 5 3 10' (top, right, bottom, left).

maskElement : String

Related to the cfg-childEls configuration which specifies named properties which correspond to component sub-elements.

The name of the element property in this component to mask when masked by a LoadMask.

Defaults to null to indicate that Components cannot by default contain a LoadMask, and that any LoadMask should be rendered into the document body.

For example, Panels use "el" to indicate that the whole panel should be masked. This could be configured to be "body" so that only the body is masked and toolbars and the header are still mouse-accessible.

Defaults to:

null

maskRe : RegExp

An input mask regular expression that will be used to filter keystrokes (character being typed) that do not match. Note: It does not filter characters already in the input.

matchFieldWidth : Boolean

Whether the picker dropdown's width should be explicitly set to match the width of the field. Defaults to true.

Defaults to:

true

maxHeight : Number

bindable bind

The maximum value in pixels which this Component will set its height to.

Warning: This will override any size management applied by layout managers.

Defaults to:

null

maxLength : Number

Maximum input field length allowed by validation. This behavior is intended to provide instant feedback to the user by improving usability to allow pasting and editing or overtyping and back tracking. To restrict the maximum number of characters that can be entered into the field use the enforceMaxLength option.

Defaults to Number.MAX_VALUE.

Defaults to:

Number.MAX_VALUE

maxLengthText : String

Error text to display if the maximum length validation fails

Defaults to:

'The maximum length for this field is {0}'

maxWidth : Number

bindable bind

The maximum value in pixels which this Component will set its width to.

Warning: This will override any size management applied by layout managers.

Defaults to:

null

minChars : Number

The minimum number of characters the user must type before autocomplete and typeAhead activate.

Defaults to 4 if queryMode = 'remote' or 0 if queryMode = 'local', does not apply if editable = false.

minHeight : Number

bindable bind

The minimum value in pixels which this Component will set its height to.

Warning: This will override any size management applied by layout managers.

Defaults to:

null

minLength : Number

Minimum input field length required

Defaults to:

0

minLengthText : String

Error text to display if the minimum length validation fails.

Defaults to:

'The minimum length for this field is {0}'

minWidth : Number

bindable bind

The minimum value in pixels which this Component will set its width to.

Warning: This will override any size management applied by layout managers.

Defaults to:

null

modal : Boolean

True to make the floated component modal and mask everything behind it when displayed, false to display it without restricting access to other UI elements.

Defaults to:

false

modelValidation : Boolean

This config enables binding to your Ext.data.Model#validators. This is only processed by form fields (e.g., Ext.form.field.Text) at present, but this setting is inherited and so can be set on a parent container.

When set to true by a component or not set by a component but inherited from an ancestor container, Ext.data.Validation records are used to automatically bind validation results for any form field to which a value is bound.

While this config can be set arbitrarily high in the component hierarchy, doing so can create a lot overhead if most of your form fields do not actually rely on validators in your data model.

Using this setting for a form that is bound to an Ext.data.Model might look like this:

 {
     xtype: 'panel',
     modelValidation: true,
     items: [{
         xtype: 'textfield',
         bind: '{theUser.firstName}'
     },{
         xtype: 'textfield',
         bind: '{theUser.lastName}'
     },{
         xtype: 'textfield',
         bind: '{theUser.phoneNumber}'
     },{
         xtype: 'textfield',
         bind: '{theUser.email}'
     }]
 }

The above is equivalent to the following manual binding of validation:

 {
     xtype: 'panel',
     items: [{
         xtype: 'textfield',
         bind: {
             value:      '{theUser.firstName}'
             validation: '{theUser.validation.firstName}'
         }
     },{
         xtype: 'textfield',
         bind: {
             value:      '{theUser.lastName}'
             validation: '{theUser.validation.lastName}'
         }
     },{
         xtype: 'textfield',
         bind: {
             value:      '{theUser.phoneNumber}'
             validation: '{theUser.validation.phoneNumber}'
         }
     },{
         xtype: 'textfield',
         bind: {
             value:      '{theUser.email}'
             validation: '{theUser.validation.email}'
         }
     }]
 }

Notice that "validation" is a pseudo-association defined for all entities. See Ext.data.Model#getValidation for further details.

msgTarget : String

The location where the error message text should display. Must be one of the following values:

• qtip Display a quick tip containing the message when the user hovers over the field. This is the default.

  Ext.tip.QuickTipManager#init must have been called for this setting to work.

• title Display the message in a default browser title attribute popup.

• under Add a block div beneath the field containing the error message.
• side Add an error icon to the right of the field, displaying the message in a popup on hover.
• none Don't display any error message. This might be useful if you are implementing custom error display.
• [element id] Add the error message directly to the innerHTML of the specified element.

Defaults to:

'qtip'

name : String

The name of the field. This is used as the parameter name when including the field value in a form submit(). If no name is configured, it falls back to the inputId. To prevent the field from being included in the form submit, set submitValue to false.

openCls : String

A class to be added to the field's bodyEl element when the picker is opened.

Defaults to:

'x-pickerfield-open'

overCls : String

An optional extra CSS class that will be added to this component's Element when the mouse moves over the Element, and removed when the mouse moves out. This can be useful for adding customized 'active' or 'hover' styles to the component or any of its children using standard CSS rules.

Defaults to:

''

Available since: 2.3.0

padding : Number / String

Specifies the padding for this component. The padding can be a single numeric value to apply to all sides or it can be a CSS style specification for each style, for example: '10 5 3 10' (top, right, bottom, left).

pageSize : Number

If greater than 0, a Ext.toolbar.Paging is displayed in the footer of the dropdown list and the filter queries will execute with page start and limit parameters. Only applies when queryMode = 'remote'.

Defaults to:

0

pickerAlign : String

The alignment position with which to align the picker. Defaults to "tl-bl?"

Defaults to:

'tl-bl?'

pickerOffset : Number[]

An offset [x,y] to use in addition to the pickerAlign when positioning the picker. Defaults to undefined.

plugins : Ext.plugin.Abstract[] / Ext.plugin.Abstract / Object[] / Object / Ext.enums.Plugin[] / Ext.enums.Plugin

An array of plugins to be added to this component. Can also be just a single plugin instead of array.

Plugins provide custom functionality for a component. The only requirement for a valid plugin is that it contain an init method that accepts a reference of type Ext.Component. When a component is created, if any plugins are available, the component will call the init method on each plugin, passing a reference to itself. Each plugin can then call methods or respond to events on the component as needed to provide its functionality.

Plugins can be added to component by either directly referencing the plugin instance:

plugins: [Ext.create('Ext.grid.plugin.CellEditing', {clicksToEdit: 1})],

By using config object with ptype:

plugins: {ptype: 'cellediting', clicksToEdit: 1},

Or with just a ptype:

plugins: ['cellediting', 'gridviewdragdrop'],

See Ext.enums.Plugin for list of all ptypes.

Available since: 2.3.0

preventMark : Boolean

true to disable displaying any error message set on this object.

Defaults to:

false

publishes : String / String[] / Object

bindable bind

One or more names of config properties that this component should publish to its ViewModel. Generally speaking, only properties defined in a class config block (including ancestor config blocks and mixins) are eligible for publishing to the viewModel. Some components override this and publish their most useful configs by default.

Note: We'll discuss publishing properties not found in the config block below.

Values determined to be invalid by component (often form fields and model validations) will not be published to the ViewModel.

This config uses the cfg-reference to determine the name of the data object to place in the ViewModel. If reference is not set then this config is ignored.

By using this config and cfg-reference you can bind configs between components. For example:

 ...
     items: [{
         xtype: 'textfield',
         reference: 'somefield',  // component's name in the ViewModel
         publishes: 'value' // value is not published by default
     },{
         ...
     },{
         xtype: 'displayfield',
         bind: 'You have entered "{somefield.value}"'
     }]
 ...

Classes must provide this config as an Object:

 Ext.define('App.foo.Bar', {
     publishes: {
         foo: true,
         bar: true
     }
 });

This is required for the config system to properly merge values from derived classes.

For instances this value can be specified as a value as show above or an array or object as follows:

 {
     xtype: 'textfield',
     reference: 'somefield',
     publishes: [
         'value',
         'rawValue',
         'dirty'
     ]
 }

 // This achieves the same result as the above array form.
 {
     xtype: 'textfield',
     reference: 'somefield',
     publishes: {
         value: true,
         rawValue: true,
         dirty: true
     }
 }

In some cases, users may want to publish a property to the viewModel that is not found in a class config block. In these situations, you may utilize publishState if the property has a setter method. Let's use setFieldLabel as an example:

  setFieldLabel: function(fieldLabel) {
      this.callParent(arguments);
      this.publishState('fieldLabel', fieldLabel);
  }

With the above chunk of code, fieldLabel may now be published to the viewModel.

Defaults to:

null

Available since: 5.0.0

queryCaching : Boolean

When true, this prevents the combo from re-querying (either locally or remotely) when the current query is the same as the previous query.

Defaults to:

true

queryDelay : Number

The length of time in milliseconds to delay between the start of typing and sending the query to filter the dropdown list.

Defaults to 500 if queryMode = 'remote' or 10 if queryMode = 'local'

queryMode : String

The mode in which the ComboBox uses the configured Store. Acceptable values are:

• 'remote' :

  In queryMode: 'remote', the ComboBox loads its Store dynamically based upon user interaction.

  This is typically used for "autocomplete" type inputs, and after the user finishes typing, the Store is loaded.

  A parameter containing the typed string is sent in the load request. The default parameter name for the input string is query, but this can be configured using the queryParam config.

  In queryMode: 'remote', the Store may be configured with remoteFilter: true, and further filters may be programatically added to the Store which are then passed with every load request which allows the server to further refine the returned dataset.

  Typically, in an autocomplete situation, hideTrigger is configured true because it has no meaning for autocomplete.

• 'local' :

  ComboBox loads local data

  var combo = new Ext.form.field.ComboBox({
      renderTo: document.body,
      queryMode: 'local',
      store: new Ext.data.ArrayStore({
          id: 0,
          fields: [
              'myId',  // numeric value is the key
              'displayText'
          ],
          data: [[1, 'item1'], [2, 'item2']]  // data is local
      }),
      valueField: 'myId',
      displayField: 'displayText',
      triggerAction: 'all'
  });
  

Defaults to:

'remote'

queryParam : String

Name of the parameter used by the Store to pass the typed string when the ComboBox is configured with queryMode: 'remote'. If explicitly set to a falsy value it will not be sent.

Defaults to:

'query'

readOnly : Boolean

bindable bind

true to prevent the user from changing the field, and hide all triggers.

readOnlyCls : String

The CSS class applied to the component's main element when it is readOnly.

Defaults to:

Ext.baseCSSPrefix + 'form-readonly'

reference : String

bindable bind

Specifies a name for this component inside its component hierarchy. This name must be unique within its view or its Ext.app.ViewController. See the documentation in Ext.container.Container for more information about references.

Note: Valid identifiers start with a letter or underscore and are followed by zero or more additional letters, underscores or digits. References are case sensitive.

Defaults to:

null

regex : RegExp

A JavaScript RegExp object to be tested against the field value during validation. If the test fails, the field will be marked invalid using either regexText or invalidText.

regexText : String

The error text to display if regex is used and the test fails during validation

Defaults to:

''

region : "north" / "south" / "east" / "west" / "center"

Defines the region inside Ext.layout.container.Border.

Possible values:

• north - Positions component at top.
• south - Positions component at bottom.
• east - Positions component at right.
• west - Positions component at left.
• center - Positions component at the remaining space. There must be a component with region: "center" in every border layout.

Defaults to:

undefined

renderConfig : Object

renderConfig wraps configs that do not get applied until after the component is rendered. Unlike normal config system properties, renderConfigs use a special setter method to store values on the instance instead of running the apply and update methods if it is called before the component is rendered. Then, after the component has been rendered, these values are processed by the normal apply and update method for the config.

This means that calling the get method for the config prior to render will return whatever raw value has been set, while calling the getter after render will return the value after processing by the config's apply method. If this distinction needs to be made, it is the caller's responsibility to check for the rendered state and handle such intermediate config values.

renderData : Object

The data used by renderTpl in addition to the following property values of the component:

• id
• ui
• uiCls
• baseCls
• componentCls
• frame

See renderSelectors and cfg-childEls for usage examples.

renderTo : String / HTMLElement / Ext.dom.Element

Specify the id of the element, a DOM element or an existing Element that this component will be rendered into.

Notes:

Do not use this option if the Component is to be a child item of a Ext.container.Container. It is the responsibility of the Ext.container.Container's layout manager to render and manage its child items.

When using this config, a call to render() is not required.

See also: method-render.

Available since: 2.3.0

repeatTriggerClick : Boolean

true to attach a Ext.util.ClickRepeater to the trigger(s). Click repeating behavior can also be configured on the individual trigger instances using the trigger's repeatClick config.

Defaults to:

false

requiredCls : String

The CSS class to apply to a required field, i.e. a field where allowBlank is false.

Defaults to:

'x-form-required-field'

resizable : Boolean / Object

Specify as true to apply a Ext.resizer.Resizer to this Component after rendering.

May also be specified as a config object to be passed to the constructor of Ext.resizer.Resizer to override any defaults. By default the Component passes its minimum and maximum size, and uses Ext.resizer.Resizer#dynamic: false

resizeHandles : String

A valid Ext.resizer.Resizer handles config string. Only applies when resizable = true.

Defaults to:

'all'

saveDelay : Number

A buffer to be applied if many state events are fired within a short period.

Defaults to:

100

scrollable : Boolean / String / Object

bindable bind

Configuration options to make this Component scrollable. Acceptable values are:

• true to enable auto scrolling.
• false (or null) to disable scrolling - this is the default.
• x or horizontal to enable horizontal scrolling only
• y or vertical to enable vertical scrolling only

Also accepts a configuration object for a Ext.scroll.Scroller if if advanced configuration is needed.

The getter for this config returns the Ext.scroll.Scroller instance. You can use the Scroller API to read or manipulate the scroll position:

// scrolls the component to 5 on the x axis and 10 on the y axis
component.getScrollable().scrollTo(5, 10);

Defaults to:

null

selection : Ext.data.Model

bindable bind

The selected model. Typically used with binding.

Defaults to:

null

selectOnTab : Boolean

Whether the Tab key should select the currently highlighted item.

Defaults to:

true

session : Boolean / Object / Ext.data.Session

bindable bind

If provided this creates a new Session instance for this component. If this is a Container, this will then be inherited by all child components.

To create a new session you can specify true:

 Ext.create({
     xtype: 'viewport',
     session: true,

     items: [{
         ...
     }]
 });

Alternatively, a config object can be provided:

 Ext.create({
     xtype: 'viewport',
     session: {
         ...
     },

     items: [{
         ...
     }]
 });

Defaults to:

null

shadow : String / Boolean

Specifies whether the floating component should be given a shadow. Set to true to automatically create an Ext.Shadow, or a string indicating the shadow's display Ext.Shadow#mode. Set to false to disable the shadow.

Defaults to:

'sides'

shadowOffset : Number

Number of pixels to offset the shadow.

shim : Boolean

true to enable an iframe shim for this Component to keep windowed objects from showing through.

shrinkWrap : Boolean / Number

The possible values for shrinkWrap are:

• 0 (or false): Neither width nor height depend on content.
• 1: Width depends on content (shrink wraps), but height does not.
• 2: Height depends on content (shrink wraps), but width does not.
• 3 (or true): Both width and height depend on content (shrink wrap).

In CSS terms, shrink-wrap width is analogous to an inline-block element as opposed to a block-level element.

Non-Panel Components

The shrinkWrap config is a class-level config and should be used when defining a subclass. It is not intended to be set as a config on instances of a given component.

For non-Panel components, shrinkWrap is a descriptive config only. It should be set when defining your own custom class including the DOM elements used to construct the component. The shrinkWrap property does not itself apply styling on the component elements. Rather, it should describe the CSS styling you've applied to your custom component (refer to the numeric matrix above).

When a component is owned by a container the layout of that container will inspect the component's shrinkWrap property during layout. The layout then uses the content-wrapping policy described by shrinkWrap to correctly size and position the container's child items.

Defaults to:

2

stateEvents : String[]

An array of events that, when fired, should trigger this object to save its state. stateEvents defaults to the stateEvents associated with the component you are using. Any events you statically set will be appended to that list. stateEvents may be any type of event supported by this object, including browser or custom events (e.g., ['click', 'customerchange']).

See stateful for an explanation of saving and restoring object state. By default the following stateEvents are added:

• event-resize - (added by Ext.Component)
• event-change

stateful : Boolean / Object

bindable bind

A flag which causes the object to attempt to restore the state of internal properties from a saved state on startup. The object must have a stateId for state to be managed.

Auto-generated ids are not guaranteed to be stable across page loads and cannot be relied upon to save and restore the same state for a object.

For state saving to work, the state manager's provider must have been set to an implementation of Ext.state.Provider which overrides the set and get methods to save and recall name/value pairs. A built-in implementation, Ext.state.CookieProvider is available.

To set the state provider for the current page:

Ext.state.Manager.setProvider(new Ext.state.CookieProvider({
    expires: new Date(new Date().getTime()+(1000*60*60*24*7)), //7 days from now
}));

A stateful object attempts to save state when one of the events listed in the stateEvents configuration fires.

To save state, a stateful object first serializes its state by calling getState.

The Component base class implements getState to save its width and height within the state only if they were initially configured, and have changed from the configured value.

The Panel class saves its collapsed state in addition to that.

The Grid class saves its column state and store state (sorters and filters and grouper) in addition to its superclass state.

If there is more application state to be save, the developer must provide an implementation which first calls the superclass method to inherit the above behaviour, and then injects new properties into the returned object.

The value yielded by getState is passed to Ext.state.Manager#set which uses the configured Ext.state.Provider to save the object keyed by the stateId.

During construction, a stateful object attempts to restore its state by calling Ext.state.Manager#get passing the stateId

The resulting object is passed to applyState*. The default implementation of applyState simply copies properties into the object, but a developer may override this to support restoration of more complex application state.

You can perform extra processing on state save and restore by attaching handlers to the beforestaterestore, staterestore, beforestatesave and statesave events. In some simple cases, passing an object for the stateful config may suffice. If an object is provided, the properties of that object are used to include or exclude stateful properties returned by getState. For example:

 stateful: {
     height: false, // never persist the height
     width: true    // always persist the width
 }

The above is roughly equivalent to the following:

 getState: function () {
     var state = this.callParent();

     delete state.height;
     state.width = this.width;

     return state;
 }

Defaults to:

false

stateId : String

The unique id for this object to use for state management purposes.

See stateful for an explanation of saving and restoring state.

stripCharsRe : RegExp

A JavaScript RegExp object used to strip unwanted content from the value during input. If stripCharsRe is specified, every character sequence matching stripCharsRe will be removed.

style : String / Object

bindable bind

A custom style specification to be applied to this component's Element. Should be a valid argument to Ext.dom.Element#applyStyles.

new Ext.panel.Panel({
    title: 'Some Title',
    renderTo: Ext.getBody(),
    width: 400, height: 300,
    layout: 'form',
    items: [{
        xtype: 'textarea',
        style: {
            width: '95%',
            marginBottom: '10px'
        }
    },
    new Ext.button.Button({
        text: 'Send',
        minWidth: '100',
        style: {
            marginBottom: '10px'
        }
    })
    ]
});

Available since: 1.1.0

var name = Ext.create({
    xtype: 'component',
    renderTo: Ext.getBody(),
    html: 'Phineas Flynn'
});

// two-param syntax
name.setStyle('color', 'white');

// single-param syntax
name.setStyle({
    fontWeight: 'bold',
    backgroundColor: 'gray',
    padding: '10px'
});

submitValue : Boolean

Setting this to false will prevent the field from being submitted even when it is not disabled.

Defaults to:

true

tabIndex : Number

bindable bind

Sets a DOM tabIndex for this field. tabIndex may be set to -1 in order to remove the field from the tab rotation.

Note: tabIndex only applies to fields that are rendered. It does not effect fields built via applyTo

toFrontOnShow : Boolean

True to automatically call toFront when the method-show method is called on an already visible, floating component.

Defaults to:

true

touchAction : Object

bindable bind

Emulates the behavior of the CSS href="https://www.w3.org/TR/pointerevents/#the-touch-action-css-property" class="external-link" target="_blank">https://www.w3.org/TR/pointerevents/#the-touch-action-css-property touch-action property in a cross-browser compatible manner.

Keys in this object are touch action names, and values are false to disable a touch action or true to enable it. Accepted keys are:

• panX
• panY
• pinchZoom
• doubleTapZoom

All touch actions are enabled (true) by default, so it is usually only necessary to specify which touch actions to disable. For example, the following disables only horizontal scrolling and pinch-to-zoom on the component's main element:

touchAction: {
    panX: false,
    pinchZoom: false
}

Touch actions can be specified on child elements using the child element name, for example:

// disables horizontal scrolling on the main element, and double-tap-zoom
// on the child element named "body"
touchAction: {
    panY: false
    body: {
        doubleTapZoom: false
    }
}

The primary motivation for setting the touch-action of an element is to prevent the browser's default handling of a gesture such as pinch-to-zoom, or drag-to-scroll, so that the application can implement its own handling of that gesture on the element. Suppose, for example, a component has a custom drag handler on its element and wishes to prevent horizontal scrolling of its container while it is being dragged:

Ext.create('Ext.Component', {
    touchAction: {
        panX: false
    },
    listeners: {
        drag: function(e) {
            // implement drag logic
        }
    }
});

Defaults to:

null

tpl : Ext.XTemplate / Ext.Template / String / String[]

An Ext.Template, Ext.XTemplate or an array of strings to form an Ext.XTemplate. Used in conjunction with the data and tplWriteMode configurations.

Available since: 3.4.0

tplWriteMode : String

The Ext.(X)Template method to use when updating the content area of the Component. See Ext.XTemplate#overwrite for information on default mode.

Defaults to:

'overwrite'

Available since: 3.4.0

transform : String / HTMLElement / Ext.dom.Element

The id, DOM node or Ext.dom.Element of an existing HTML <select> element to convert into a ComboBox. The target select's options will be used to build the options in the ComboBox dropdown; a configured store will take precedence over this.

transformInPlace : Boolean

true to automatically render this combo box in place of the select element that is being transformed. If false, this combo will be rendered using the normal rendering, either as part of a layout, or using renderTo or method-render.

Defaults to:

true

triggerAction : String

The action to execute when the trigger is clicked.

• 'all' :

  run the query specified by the allQuery config option

• 'last' :

  run the query using the last query value.

• 'query' :

  run the query using the raw value.

See also queryParam.

Defaults to:

'all'

triggerCls : String

An additional CSS class used to style the trigger button. The trigger will always get the Ext.form.trigger.Trigger#baseCls by default and triggerCls will be appended if specified.

Defaults to:

'x-form-arrow-trigger'

triggers : Object

bindable bind

Ext.form.trigger.Trigger to use in this field. The keys in this object are unique identifiers for the triggers. The values in this object are Ext.form.trigger.Trigger configuration objects.

Ext.create('Ext.form.field.Text', {
    renderTo: document.body,
    fieldLabel: 'My Custom Field',
    triggers: {
        foo: {
            cls: 'my-foo-trigger',
            handler: function() {
                console.log('foo trigger clicked');
            }
        },
        bar: {
            cls: 'my-bar-trigger',
            handler: function() {
                console.log('bar trigger clicked');
            }
        }
    }
});

The weight value may be a negative value in order to position custom triggers ahead of default triggers like that of ComboBox.

Ext.create('Ext.form.field.ComboBox', {
    renderTo: Ext.getBody(),
    fieldLabel: 'My Custom Field',
    triggers: {
        foo: {
            cls: 'my-foo-trigger',
            weight: -2, // negative to place before default triggers
            handler: function() {
                console.log('foo trigger clicked');
            }
        },
        bar: {
            cls: 'my-bar-trigger',
            weight: -1,
            handler: function() {
                console.log('bar trigger clicked');
            }
        }
    }
});

Defaults to:

undefined

triggerWrapCls : String

The CSS class that is added to the div wrapping the input element and trigger button(s).

Defaults to:

Ext.baseCSSPrefix + 'form-trigger-wrap'

twoWayBindable : String / String[] / Object

bindable bind

This object holds a map of config properties that will update their binding as they are modified. For example, value is a key added by form fields. The form of this config is the same as publishes.

This config is defined so that updaters are not created and added for all bound properties since most cannot be modified by the end-user and hence are not appropriate for two-way binding.

Defaults to:

null

typeAhead : Boolean

true to populate and autoselect the remainder of the text being typed after a configurable delay (typeAheadDelay) if it matches a known value.

Defaults to:

false

typeAheadDelay : Number

The length of time in milliseconds to wait until the typeahead text is displayed if typeAhead = true

Defaults to:

250

ui : String

bindable bind

A UI style for a component.

Defaults to:

'default'

userCls : String / String[]

bindable bind

One or more CSS classes to add to the component's primary element. This config is intended solely for use by the component instantiator (the "user"), not by derived classes.

For example:

 items: [{
     xtype: 'button',
     userCls: 'my-button'
 ...
 }]

Defaults to:

null

validateBlank : Boolean

Specify as true to modify the behaviour of allowBlank so that blank values are not passed as valid, but are subject to any configure vtype validation.

Defaults to:

false

validateOnBlur : Boolean

Whether the field should validate when it loses focus. This will cause fields to be validated as the user steps through the fields in the form regardless of whether they are making changes to those fields along the way. See also validateOnChange.

Defaults to:

true

validateOnChange : Boolean

Specifies whether this field should be validated immediately whenever a change in its value is detected. If the validation results in a change in the field's validity, a validitychange event will be fired. This allows the field to show feedback about the validity of its contents immediately as the user is typing.

When set to false, feedback will not be immediate. However the form will still be validated before submitting if the clientValidation option to Ext.form.Basic#doAction is enabled, or if the field or form are validated manually.

See also Ext.form.field.Base#checkChangeEvents for controlling how changes to the field's value are detected.

Defaults to:

true

validation : Boolean / String

bindable bind

This property, when a String, contributes its value to the error state of this instance as reported by getErrors.

Defaults to:

null

validator : Function

A custom validation function to be called during field validation (getErrors). If specified, this function will be called first, allowing the developer to override the default validation process.

Ext.create('Ext.form.field.Text', {
    renderTo: document.body,
    name: 'phone',
    fieldLabel: 'Phone Number',
    validator: function (val) {
        // remove non-numeric characters
        var tn = val.replace(/[^0-9]/g,''),
            errMsg = "Must be a 10 digit telephone number";
        // if the numeric value is not 10 digits return an error message
        return (tn.length === 10) ? true : errMsg;
    }
});

Parameters

Returns