{"_id":"56d91c5607ae190b0000446b","category":{"_id":"56d91c5507ae190b00004464","__v":1,"project":"5515ba4981faf83900d2b10c","pages":["56d91c5607ae190b00004469","56d91c5607ae190b0000446a","56d91c5607ae190b0000446b","56d91c5607ae190b0000446c","56d91c5607ae190b0000446d","56d91c5607ae190b0000446e","56d91c5607ae190b0000446f","56d91c5607ae190b00004470","56d91c5607ae190b00004471","56d91c5607ae190b00004472","56d91c5607ae190b00004473","56d91c5607ae190b00004474","56d91c5607ae190b00004475","56d91c5607ae190b00004476"],"version":"56d91c5507ae190b00004460","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-03-27T20:15:06.295Z","from_sync":false,"order":0,"slug":"guides","title":"Guides"},"project":"5515ba4981faf83900d2b10c","version":{"_id":"56d91c5507ae190b00004460","__v":1,"project":"5515ba4981faf83900d2b10c","createdAt":"2016-03-04T05:25:41.052Z","releaseDate":"2016-03-04T05:25:41.052Z","categories":["56d91c5507ae190b00004464","56d91c5507ae190b00004465","56d91c5507ae190b00004466","56d91c5507ae190b00004467","56d91c5507ae190b00004468"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"8.0.0","version":"8.0.0"},"__v":2,"user":"54e3723b8ef7552300409bf4","updates":["558c1f669651c22300361297","575aba0de12cf20e002f2fe5"],"next":{"pages":[],"description":""},"createdAt":"2015-05-01T12:36:20.494Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"You pass an array of field configuration objects to the [formly-form](doc:formly-form) directive.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"api-check\",\n  \"body\": \"These are validated using [api-check](https://github.com/kentcdodds/apiCheck.js) which will ensure that you're assigning the right properties and the right types. Aside from being required to specify the correct types, you are also required to set at least a `type`, `template`, or `templateUrl`. These attributes are mutually exclusive. All other properties are optional. Finally, you can only specify the properties listed below. Additional properties will result in an error. If you need custom properties, use `templateOptions` or `data`.\"\n}\n[/block]\nBelow are descriptions of the different properties of the field configuration object.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"type (string)\"\n}\n[/block]\n[Example](http://angular-formly.com/#/example/intro/introduction) | [Lesson](https://egghead.io/lessons/angularjs-introduction-to-angular-formly?pl=7)\n\nThe `type` of field to be rendered. This is the recommended method for defining fields. Types must be pre-defined using [formlyConfig](doc:formlyconfig).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"template (string || function)\"\n}\n[/block]\n[Example](http://angular-formly.com/#/example/intro/introduction) | [Lesson](https://egghead.io/lessons/angularjs-introduction-to-angular-formly?pl=7)\n\nCan be set instead of `type` or `templateUrl` to use a custom html template form field. Recommended to be used with one-liners mostly (like a directive), or if you're using webpack with the ability to [require templates](https://egghead.io/lessons/angularjs-angular-with-webpack-requiring-templates) :-)\n\nIf a function is passed, it is invoked with the field configuration object and can return either a string for the template or a promise that resolves to a string.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"This can be used to add HTML instead of a form field.\",\n  \"title\": \"Add Normal HTML\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"vm.fields = [\\n  {\\n    noFormControl: true,\\n    template: '<p>Some text here</p>'\\n  },\\n  // templateUrl works too\\n  {\\n    noFormControl: true,\\n    templateUrl: 'path/to/template.html'\\n  }\\n];\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nSee below for an explanation on why `noFormControl` is needed.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"templateUrl (string || function)\"\n}\n[/block]\n[Example](http://angular-formly.com/#/example/intro/introduction) | [Lesson](https://egghead.io/lessons/angularjs-introduction-to-angular-formly?pl=7)\n\nCan be set instead of `type` or `template` to use a custom html template form field. Works just like a directive `templateUrl` and uses the [`$templateCache`](https://docs.angularjs.org/api/ng/service/$templateCache)\n\nIf a function is passed, it is invoked with the field configuration object and can return either a string for the templateUrl or a promise that resolves to a string.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"key (string)\"\n}\n[/block]\n[Example](http://angular-formly.com/#/example/intro/introduction) | [Lesson](https://egghead.io/lessons/angularjs-introduction-to-angular-formly?pl=7)\n\nBy default form models are keyed by location in the form array, you can override this by specifying a `key`.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"vm.model = {};\\nvm.fields = [\\n  {\\n    // this field's ng-model will be bound to vm.model.username\\n    key: 'username',\\n    type: 'input'\\n  },\\n  {\\n    key: 'name.first',\\n    type: 'input'\\n  },\\n  {\\n    key: 'name.last',\\n    type: 'input'\\n  }\\n];\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"defaultValue (any)\"\n}\n[/block]\n[Example](http://angular-formly.com/#/example/field-options/default-value)\n\nUse `defaultValue` to initialize it the model. If this is provided and the value of the model at compile-time is undefined, then the value of the model will be assigned to `defaultValue`.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Use the model\",\n  \"body\": \"The `<formly-form>` represents the current state of the model and that's it. So if you want to default values in the form, simply initialize your model with that state and you're good. However, there are some use cases where it is much easier to use the form config to initialize the model, which is why this property was added.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"hide (boolean)\"\n}\n[/block]\nWhether to hide the field. Defaults to false. If you wish this to be conditional, use `hideExpression`. See below.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Unless otherwise specified by the `hide-directive` attribute on the [formly-form](doc:formly-form) or the preconfiguration in `[formlyConfig](doc:formlyconfig)`\",\n  \"title\": \"Uses ng-if\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"hideExpression (string || function)\"\n}\n[/block]\nThis is similar to `expressionProperties` with a slight difference. You should (hopefully) never notice the difference with the most common use case. This is available due to limitations with `expressionProperties` and `ng-if` not working together very nicely.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"model (object || string)\"\n}\n[/block]\n[Example](http://angular-formly.com/#/example/field-options/model)\n\nBy default, the `model` passed to the [`formly-field`](doc:formly-field) directive is the same as the `model` passed to the [`formly-form`](doc:formly-form). However, if the field has a `model` specified, then it is used for that field (and that field only). In addition, a deep watch is added to the `formly-field` directive's scope to run the `expressionProperties` when the specified `model` changes.\n\nNote, the `formly-form` directive will allow you to specify a string which is an (almost) formly expression which allows you to define the model as relative to the scope of the form.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"expressionProperties (object)\"\n}\n[/block]\n[Example](http://angular-formly.com/#/example/field-options/expression-properties)\n\nAn object where the key is a property to be set on the main field config and the value is an expression used to assign that property. The value is a [formly expressions](doc:formly-expressions). The returned value is wrapped in `$q.when` so you can return a promise from your function :-)\n\n[NG-NL Talk Excerpt](https://youtu.be/o90TMDL3OYc?t=25m45s)\n\nFor example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"vm.fields = [\\n  {\\n    key: 'myThing',\\n    type: 'someType',\\n    expressionProperties: {\\n      'templateOptions.label': '$viewValue', // this would make the label change to what the user has typed\\n\\n       // this would set that property on data to be whether or not model.myThing.length > 5\\n      'data.someproperty.somethingdeeper.whateveryouwant': 'model.myThing.length > 5'\\n    }\\n  }\\n];\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"className (string)\"\n}\n[/block]\nYou can specify your own class that will be applied to the `formly-field` directive (or `ng-form` of a `fieldGroup`).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"id (string)\"\n}\n[/block]\nThis allows you to specify the `id` of your field (which will be used for its `name` as well unless a `name` is provided). Note, you can also override the `id` generation code using the [formlyConfig](doc:formlyconfig) [`extra`](http://docs.angular-formly.com/docs/formlyconfig#extras) called `getFieldId`.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Avoid this\",\n  \"body\": \"If you don't have to do this, don't. Specifying IDs makes it harder to re-use things and it's just extra work. Part of the beauty that angular-formly provides is the fact that you don't need to concern yourself with making sure that this is unique.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"name (string)\"\n}\n[/block]\nIf you wish to, you can specify a specific `name` for your `ng-model`. This is useful if you're posting the form to a server using techniques of yester-year.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Avoid this\",\n  \"body\": \"If you don't have to do this, don't. It's just extra work. Part of the beauty that angular-formly provides is the fact that you don't need to concern yourself with stuff like this.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"extras (object)\"\n}\n[/block]\nThis object holds a few extra configuration options that are not commonly used\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"validateOnModelChange\",\n    \"0-1\": \"boolean\",\n    \"0-2\": \"This will cause the validation to run whenever anything in the `model` or `formState` changes. This is useful in a case where the value of one field determines the validity of another (like [here](http://angular-formly.com/#/example/other/matching-two-fields))\",\n    \"1-2\": \"If, for some reason, you want to have the built-in ngModelAttrsManipulator skip over a template, this is the way to do it (like in [this example](http://angular-formly.com/#/example/other/button))\",\n    \"1-0\": \"skipNgModelAttrsManipulator\",\n    \"1-1\": \"boolean\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"data (object)\"\n}\n[/block]\nThis is reserved for the developer. You have our guarantee to be able to use this and not worry about future versions of formly overriding your usage and preventing you from upgrading :-)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"templateOptions (object)\"\n}\n[/block]\n[Example](http://angular-formly.com/#/example/intro/introduction) | [Lesson](https://egghead.io/lessons/angularjs-introduction-to-angular-formly?pl=7)\n\nThis is reserved for the templates. Any template-specific options go in here. Look at your specific template implementation to know the options required for this. \n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Common Properties\",\n  \"body\": \"angular-formly ships with the [ngModelAttrsTemplateManipulator](doc:ngmodelattrstemplatemanipulator). This will automatically add properties like `required`, and `placeholder` to the `ng-model` element in your field.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"templateManipulator (object of arrays of functions)\"\n}\n[/block]\nAllows you to specify custom template manipulators for this specific field. (use `defaultOptions` in a type configuration if you want it to apply to all fields of a certain type).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"vm.fields = [\\n  {\\n    template: 'foo',\\n    templateManipulators: {\\n      preWrapper: [\\n          function(template, options, scope) {\\n          // this is called for this field only before wrappers and other manipulators or wrappers\\n          return template;\\n        }\\n      ],\\n      postWrapper: [\\n          function(template, options, scope) {\\n          // this is called for this field only after wrappers and before other manipulators\\n          return template;\\n        }\\n      ]\\n    }\\n  }\\n];\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"wrapper (string || array of strings)\"\n}\n[/block]\n[Example](http://angular-formly.com/#/example/advanced/template-wrappers)\n\nThis makes reference to `setWrapper` in [formlyConfig](doc:formlyconfig). It is expected to be the name of the wrapper. If given an array, the formly field template will be wrapped by the first wrapper, then the second, then the third, etc. You can also specify these as part of a `type` (which is the recommended approach).\n\nSetting this property to `null` will remove the wrappers for the type for this field. Overriding existing wrappers for the type is currently not possible. The recommended workaround is to define a new type, see [#371](https://github.com/formly-js/angular-formly/issues/371).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"ngModelElAttrs (object)\"\n}\n[/block]\nThis allows you to place attributes on the `ng-model` element.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"vm.fields = [\\n  {\\n    template: '<input ng-model=\\\"model[options.key]\\\" />',\\n    ngModelElAttrs: {\\n      'some-custom-directive': 'theValue'\\n    }\\n  }\\n];\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nWould result in:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<input ng-model=\\\"model[options.key]\\\" some-custom-directive=\\\"theValue\\\" />\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nThis is a less powerful, but much more simple API than `ngModelAttrs`.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"ngModelAttrs (object)\"\n}\n[/block]\nThis is used by [ngModelAttrsTemplateManipulator](doc:ngmodelattrstemplatemanipulator) to automatically add attributes to the ng-model element of field templates. You will likely not use this often. This object is a little complex, but extremely powerful. It's best to explain this api via an example. For more information, see the guide on [ngModelAttrs](doc:ngmodelattrs).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"controller (controller name as string || controller function)\"\n}\n[/block]\n[Example](http://angular-formly.com/#/example/advanced/custom-controller-and-link)\n\nThis is a great way to add custom behavior to a specific field. It is injectable with the $scope of the field, and anything else you have in your injector.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Injectable function\",\n  \"body\": \"This is invoked using the `$injector`. If you minify your code (as you should) then you should make sure that this function is annotated correctly so dependency injection works properly. See the [angular documentation on di](https://docs.angularjs.org/guide/di#dependency-annotation) for more information.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"link (link function)\"\n}\n[/block]\n[Example](http://angular-formly.com/#/example/advanced/custom-controller-and-link)\n\nThis allows you to specify a link function. It is invoked after your template has finished compiling. You are passed the normal arguments for a normal link function.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"optionsTypes (string || array of strings)\"\n}\n[/block]\n[Example](http://angular-formly.com/#/example/custom-types/default-options)\n\nAllows you to specify extra types to get options from. Duplicate options are overridden in later priority (index `1` will override index `0` properties). Also, these are applied *after* the `type`'s `defaultOptions` and hence will override any duplicates of those properties as well.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"modelOptions\"\n}\n[/block]\nAllows you to take advantage of `ng-model-options` directive. Formly's built-in templateManipulator (see below) will add this attribute to your `ng-model` element automatically if this property exists. Note, if you use the `getter/setter` option, formly's templateManipulator will change the value of `ng-model` to `options.value` which is a getterSetter that formly adds to field options. For more information on ng-model-options, see [this ng-conf talk](https://www.youtube.com/watch?v=k3t3ov6xHDw) and [these](https://egghead.io/lessons/angularjs-new-in-angular-1-3-ng-model-options-getters-and-setters) [egghead](https://egghead.io/lessons/angularjs-new-in-angular-1-3-ng-model-options-updateon-and-debounce) [lessons](https://egghead.io/lessons/angularjs-new-in-angular-1-3-ngmodeloptions-allows-you-to-set-a-timezone-on-your-model).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"noFormControl (boolean)\"\n}\n[/block]\nUsed to tell angular-formly to not attempt to add the `formControl` property to your object. This is useful for things like validation, but not necessary if your \"field\" doesn't use `ng-model` (if it's just a horizontal line for example). Defaults to undefined.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"watcher (object|array of watches)\"\n}\n[/block]\n[Example](http://angular-formly.com/#/example/field-options/watchers)\n\nAn object which has at least two properties called `expression` and `listener`. The `watch.expression` is added to the `formly-form` directive's scope (to allow it to run even when `hide` is true). You can specify a type (`$watchCollection` or `$watchGroup`) via the `watcher.type` property (defaults to `$watch`) and whether you want it to be a deep watch via the `watcher.deep` property (defaults to `false`).\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Not a normal watch/formly expression\",\n  \"body\": \"This differs slightly from a normal `$watch` function in very useful ways. See [Formly Expressions](doc:formly-expressions) for more information.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"validators (object)\"\n}\n[/block]\n[Example](http://angular-formly.com/#/example/intro/codementor) | [Lesson](https://egghead.io/lessons/angularjs-angular-formly-custom-validation?pl=7)\n\nAn object where the keys are the name of the validator and the values are [Formly Expressions](doc:formly-expressions) (can be a string or a function)\n\nA validator passes if it returns true. A validator fails if it returns false.\n\n# Angular < 1.3\n\nFormly defaults to use the `$validators` api, which is only available in angular 1.3. If you are using 1.2, then the `$parsers` api is used which doesn't support async validation out of the box. However, formly will keep track of the validations for you and ensure that the most recently resolved/rejected promise is what takes priority. Also, while the validation is in flight, formly emulates the `$pending` api of 1.3 for your use in 1.2 as well, so you can safely use this and upgrade to 1.3 without worrying about the upgrade path for this api. You're welcome :-)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"asyncValidators (object)\"\n}\n[/block]\n[Example](http://angular-formly.com/#/example/other/unique-value-async-validation)\n\nUse this one for anything that needs to validate asynchronously. Pretty much exactly the same as the `validators` api, except it must be a function that returns a promise. A validator passes if it returns a promise that is resolved. A validator fails if it returns a promise that is rejected.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"You can alternatively specify a validator as an object with an `expression` and a `message`. This will unify how templates reference messages for when the validator has failed. Also, this should be used only for one-off messages (use `ng-messages-include` for generic messages). `message` in this case should be an expression that is evaluated in exactly the same way a validator is evaluated. The `formly-custom-validation` directive will then add an object to the field options called `validation.messages` which is a map of functions where the key is the validation name and the value is a to function which returns the evaluated message. This is especially useful when using `ng-messages`.\",\n  \"title\": \"Validator as an object\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"validation (object)\"\n}\n[/block]\nAn object with a few useful properties mostly handy when used in combination with ng-messages\n\n# validation.messages\n\nA map of [Formly Expressions](doc:formly-expressions) mapped to message names. This is really useful when you're using `ng-messages` like in [this example](http://angular-formly.com/#/example/advanced/validators).\n\n# validation.show\n\nA boolean you as the developer can set to specify to force `options.validation.errorExistsAndShouldBeVisible` to be set to true when there are `$errors`. This is useful when you're trying to call the user's attention to some fields for some reason. See [this example](http://angular-formly.com/#/example/other/force-show-error)\n\n# validation.errorExistsAndShouldBeVisible\n\nThis is set by angular-formly. This is a boolean indicating whether an error message should be shown. Because you generally only want to show error messages when the user has interacted with a specific field, this value is set to true based on this rule: `field invalid && (field touched || validation.show)` (with slight difference for pre-angular 1.3 because it doesn't have touched support).\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"showError - shortcut\",\n  \"body\": \"Because `options.validation.errorExistsAndShouldBeVisible` is really long, template authors can use `showError` instead which is simply a shortcut for this property.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"parsers (array of formlyExpressions)\"\n}\n[/block]\nThis allows you to hook into the [`$parsers`](https://docs.angularjs.org/api/ng/type/ngModel.NgModelController#$parsers) functionality of angular\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"formatters (array of formlyExpressions)\"\n}\n[/block]\nThis allows you to hook into the [`$formatters`](https://docs.angularjs.org/api/ng/type/ngModel.NgModelController#$formatters) functionality of angular\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"value (getter/setter function)\"\n}\n[/block]\nThis is a getter/setter function for the value that your field is representing. Useful when using `getterSetter: true` in the `modelOptions` (in fact, if you don't disable the `ngModelAttrsTemplateManipulator` that comes built-in with formly, it will automagically change your field's `ng-model` attribute to use `options.value`.\n\n---\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"All properties below are added\"\n}\n[/block]\nSo you should not be setting them yourself.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Added Properties\",\n  \"body\": \"The properties listed below are added to your field configuration.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"formControl (NgModelController)\"\n}\n[/block]\nThis is the [NgModelController](https://docs.angularjs.org/api/ng/type/ngModel.NgModelController) for the field. It provides you with awesome stuff like `$errors` :-)\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"For template authors, a shortcut is provided on the `$scope` for this property called `fc`\",\n  \"title\": \"fc - shortcut\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"initialValue (any)\"\n}\n[/block]\nUsed in combination with `resetModel` and `updateInitialValue`. Basically, this is set to the value this field represents at compile time, or the last time `updateInitialValue` is called.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"resetModel (function)\"\n}\n[/block]\nWill reset the field's model and the field control to the last `initialValue`. This is used by the [formly-form](doc:formly-form)'s `options.resetModel` function.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"updateInitialValue (function)\"\n}\n[/block]\nWill reset the field's `initialValue` to the current state of the model. Useful if you load the model asynchronously. Invoke this when the model gets set. This is used by the [formly-form](doc:formly-form)'s `options.updateInitialValue` function.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"runExpressions (function)\"\n}\n[/block]\nIt is not likely that you'll ever want to invoke this function. It simply runs the `expressionProperties` expressions. It is used internally and you shouldn't have to use it, but you can if you want to, and any breaking changes to the way it works will result in a major version change, so you can rely on its api.\n[block:html]\n{\n  \"html\": \"<hr />\\n<a href=\\\"https://app.codesponsor.io/link/PKGFLnhDiFvsUA5P4kAXfiPs/formly-js/angular-formly\\\" rel=\\\"nofollow\\\"><img src=\\\"https://app.codesponsor.io/embed/PKGFLnhDiFvsUA5P4kAXfiPs/formly-js/angular-formly.svg\\\" style=\\\"width: 888px; height: 68px;\\\" alt=\\\"Sponsor\\\" /></a>\\n\"\n}\n[/block]","excerpt":"","slug":"field-configuration-object","type":"basic","title":"Field Configuration Object"}

Field Configuration Object


You pass an array of field configuration objects to the [formly-form](doc:formly-form) directive. [block:callout] { "type": "info", "title": "api-check", "body": "These are validated using [api-check](https://github.com/kentcdodds/apiCheck.js) which will ensure that you're assigning the right properties and the right types. Aside from being required to specify the correct types, you are also required to set at least a `type`, `template`, or `templateUrl`. These attributes are mutually exclusive. All other properties are optional. Finally, you can only specify the properties listed below. Additional properties will result in an error. If you need custom properties, use `templateOptions` or `data`." } [/block] Below are descriptions of the different properties of the field configuration object. [block:api-header] { "type": "basic", "title": "type (string)" } [/block] [Example](http://angular-formly.com/#/example/intro/introduction) | [Lesson](https://egghead.io/lessons/angularjs-introduction-to-angular-formly?pl=7) The `type` of field to be rendered. This is the recommended method for defining fields. Types must be pre-defined using [formlyConfig](doc:formlyconfig). [block:api-header] { "type": "basic", "title": "template (string || function)" } [/block] [Example](http://angular-formly.com/#/example/intro/introduction) | [Lesson](https://egghead.io/lessons/angularjs-introduction-to-angular-formly?pl=7) Can be set instead of `type` or `templateUrl` to use a custom html template form field. Recommended to be used with one-liners mostly (like a directive), or if you're using webpack with the ability to [require templates](https://egghead.io/lessons/angularjs-angular-with-webpack-requiring-templates) :-) If a function is passed, it is invoked with the field configuration object and can return either a string for the template or a promise that resolves to a string. [block:callout] { "type": "info", "body": "This can be used to add HTML instead of a form field.", "title": "Add Normal HTML" } [/block] [block:code] { "codes": [ { "code": "vm.fields = [\n {\n noFormControl: true,\n template: '<p>Some text here</p>'\n },\n // templateUrl works too\n {\n noFormControl: true,\n templateUrl: 'path/to/template.html'\n }\n];", "language": "javascript" } ] } [/block] See below for an explanation on why `noFormControl` is needed. [block:api-header] { "type": "basic", "title": "templateUrl (string || function)" } [/block] [Example](http://angular-formly.com/#/example/intro/introduction) | [Lesson](https://egghead.io/lessons/angularjs-introduction-to-angular-formly?pl=7) Can be set instead of `type` or `template` to use a custom html template form field. Works just like a directive `templateUrl` and uses the [`$templateCache`](https://docs.angularjs.org/api/ng/service/$templateCache) If a function is passed, it is invoked with the field configuration object and can return either a string for the templateUrl or a promise that resolves to a string. [block:api-header] { "type": "basic", "title": "key (string)" } [/block] [Example](http://angular-formly.com/#/example/intro/introduction) | [Lesson](https://egghead.io/lessons/angularjs-introduction-to-angular-formly?pl=7) By default form models are keyed by location in the form array, you can override this by specifying a `key`. [block:code] { "codes": [ { "code": "vm.model = {};\nvm.fields = [\n {\n // this field's ng-model will be bound to vm.model.username\n key: 'username',\n type: 'input'\n },\n {\n key: 'name.first',\n type: 'input'\n },\n {\n key: 'name.last',\n type: 'input'\n }\n];", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "defaultValue (any)" } [/block] [Example](http://angular-formly.com/#/example/field-options/default-value) Use `defaultValue` to initialize it the model. If this is provided and the value of the model at compile-time is undefined, then the value of the model will be assigned to `defaultValue`. [block:callout] { "type": "info", "title": "Use the model", "body": "The `<formly-form>` represents the current state of the model and that's it. So if you want to default values in the form, simply initialize your model with that state and you're good. However, there are some use cases where it is much easier to use the form config to initialize the model, which is why this property was added." } [/block] [block:api-header] { "type": "basic", "title": "hide (boolean)" } [/block] Whether to hide the field. Defaults to false. If you wish this to be conditional, use `hideExpression`. See below. [block:callout] { "type": "info", "body": "Unless otherwise specified by the `hide-directive` attribute on the [formly-form](doc:formly-form) or the preconfiguration in `[formlyConfig](doc:formlyconfig)`", "title": "Uses ng-if" } [/block] [block:api-header] { "type": "basic", "title": "hideExpression (string || function)" } [/block] This is similar to `expressionProperties` with a slight difference. You should (hopefully) never notice the difference with the most common use case. This is available due to limitations with `expressionProperties` and `ng-if` not working together very nicely. [block:api-header] { "type": "basic", "title": "model (object || string)" } [/block] [Example](http://angular-formly.com/#/example/field-options/model) By default, the `model` passed to the [`formly-field`](doc:formly-field) directive is the same as the `model` passed to the [`formly-form`](doc:formly-form). However, if the field has a `model` specified, then it is used for that field (and that field only). In addition, a deep watch is added to the `formly-field` directive's scope to run the `expressionProperties` when the specified `model` changes. Note, the `formly-form` directive will allow you to specify a string which is an (almost) formly expression which allows you to define the model as relative to the scope of the form. [block:api-header] { "type": "basic", "title": "expressionProperties (object)" } [/block] [Example](http://angular-formly.com/#/example/field-options/expression-properties) An object where the key is a property to be set on the main field config and the value is an expression used to assign that property. The value is a [formly expressions](doc:formly-expressions). The returned value is wrapped in `$q.when` so you can return a promise from your function :-) [NG-NL Talk Excerpt](https://youtu.be/o90TMDL3OYc?t=25m45s) For example: [block:code] { "codes": [ { "code": "vm.fields = [\n {\n key: 'myThing',\n type: 'someType',\n expressionProperties: {\n 'templateOptions.label': '$viewValue', // this would make the label change to what the user has typed\n\n // this would set that property on data to be whether or not model.myThing.length > 5\n 'data.someproperty.somethingdeeper.whateveryouwant': 'model.myThing.length > 5'\n }\n }\n];", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "className (string)" } [/block] You can specify your own class that will be applied to the `formly-field` directive (or `ng-form` of a `fieldGroup`). [block:api-header] { "type": "basic", "title": "id (string)" } [/block] This allows you to specify the `id` of your field (which will be used for its `name` as well unless a `name` is provided). Note, you can also override the `id` generation code using the [formlyConfig](doc:formlyconfig) [`extra`](http://docs.angular-formly.com/docs/formlyconfig#extras) called `getFieldId`. [block:callout] { "type": "warning", "title": "Avoid this", "body": "If you don't have to do this, don't. Specifying IDs makes it harder to re-use things and it's just extra work. Part of the beauty that angular-formly provides is the fact that you don't need to concern yourself with making sure that this is unique." } [/block] [block:api-header] { "type": "basic", "title": "name (string)" } [/block] If you wish to, you can specify a specific `name` for your `ng-model`. This is useful if you're posting the form to a server using techniques of yester-year. [block:callout] { "type": "warning", "title": "Avoid this", "body": "If you don't have to do this, don't. It's just extra work. Part of the beauty that angular-formly provides is the fact that you don't need to concern yourself with stuff like this." } [/block] [block:api-header] { "type": "basic", "title": "extras (object)" } [/block] This object holds a few extra configuration options that are not commonly used [block:parameters] { "data": { "h-0": "Property", "h-1": "Type", "h-2": "Description", "0-0": "validateOnModelChange", "0-1": "boolean", "0-2": "This will cause the validation to run whenever anything in the `model` or `formState` changes. This is useful in a case where the value of one field determines the validity of another (like [here](http://angular-formly.com/#/example/other/matching-two-fields))", "1-2": "If, for some reason, you want to have the built-in ngModelAttrsManipulator skip over a template, this is the way to do it (like in [this example](http://angular-formly.com/#/example/other/button))", "1-0": "skipNgModelAttrsManipulator", "1-1": "boolean" }, "cols": 3, "rows": 2 } [/block] [block:api-header] { "type": "basic", "title": "data (object)" } [/block] This is reserved for the developer. You have our guarantee to be able to use this and not worry about future versions of formly overriding your usage and preventing you from upgrading :-) [block:api-header] { "type": "basic", "title": "templateOptions (object)" } [/block] [Example](http://angular-formly.com/#/example/intro/introduction) | [Lesson](https://egghead.io/lessons/angularjs-introduction-to-angular-formly?pl=7) This is reserved for the templates. Any template-specific options go in here. Look at your specific template implementation to know the options required for this. [block:callout] { "type": "success", "title": "Common Properties", "body": "angular-formly ships with the [ngModelAttrsTemplateManipulator](doc:ngmodelattrstemplatemanipulator). This will automatically add properties like `required`, and `placeholder` to the `ng-model` element in your field." } [/block] [block:api-header] { "type": "basic", "title": "templateManipulator (object of arrays of functions)" } [/block] Allows you to specify custom template manipulators for this specific field. (use `defaultOptions` in a type configuration if you want it to apply to all fields of a certain type). [block:code] { "codes": [ { "code": "vm.fields = [\n {\n template: 'foo',\n templateManipulators: {\n preWrapper: [\n function(template, options, scope) {\n // this is called for this field only before wrappers and other manipulators or wrappers\n return template;\n }\n ],\n postWrapper: [\n function(template, options, scope) {\n // this is called for this field only after wrappers and before other manipulators\n return template;\n }\n ]\n }\n }\n];", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "wrapper (string || array of strings)" } [/block] [Example](http://angular-formly.com/#/example/advanced/template-wrappers) This makes reference to `setWrapper` in [formlyConfig](doc:formlyconfig). It is expected to be the name of the wrapper. If given an array, the formly field template will be wrapped by the first wrapper, then the second, then the third, etc. You can also specify these as part of a `type` (which is the recommended approach). Setting this property to `null` will remove the wrappers for the type for this field. Overriding existing wrappers for the type is currently not possible. The recommended workaround is to define a new type, see [#371](https://github.com/formly-js/angular-formly/issues/371). [block:api-header] { "type": "basic", "title": "ngModelElAttrs (object)" } [/block] This allows you to place attributes on the `ng-model` element. [block:code] { "codes": [ { "code": "vm.fields = [\n {\n template: '<input ng-model=\"model[options.key]\" />',\n ngModelElAttrs: {\n 'some-custom-directive': 'theValue'\n }\n }\n];", "language": "javascript" } ] } [/block] Would result in: [block:code] { "codes": [ { "code": "<input ng-model=\"model[options.key]\" some-custom-directive=\"theValue\" />", "language": "html" } ] } [/block] This is a less powerful, but much more simple API than `ngModelAttrs`. [block:api-header] { "type": "basic", "title": "ngModelAttrs (object)" } [/block] This is used by [ngModelAttrsTemplateManipulator](doc:ngmodelattrstemplatemanipulator) to automatically add attributes to the ng-model element of field templates. You will likely not use this often. This object is a little complex, but extremely powerful. It's best to explain this api via an example. For more information, see the guide on [ngModelAttrs](doc:ngmodelattrs). [block:api-header] { "type": "basic", "title": "controller (controller name as string || controller function)" } [/block] [Example](http://angular-formly.com/#/example/advanced/custom-controller-and-link) This is a great way to add custom behavior to a specific field. It is injectable with the $scope of the field, and anything else you have in your injector. [block:callout] { "type": "warning", "title": "Injectable function", "body": "This is invoked using the `$injector`. If you minify your code (as you should) then you should make sure that this function is annotated correctly so dependency injection works properly. See the [angular documentation on di](https://docs.angularjs.org/guide/di#dependency-annotation) for more information." } [/block] [block:api-header] { "type": "basic", "title": "link (link function)" } [/block] [Example](http://angular-formly.com/#/example/advanced/custom-controller-and-link) This allows you to specify a link function. It is invoked after your template has finished compiling. You are passed the normal arguments for a normal link function. [block:api-header] { "type": "basic", "title": "optionsTypes (string || array of strings)" } [/block] [Example](http://angular-formly.com/#/example/custom-types/default-options) Allows you to specify extra types to get options from. Duplicate options are overridden in later priority (index `1` will override index `0` properties). Also, these are applied *after* the `type`'s `defaultOptions` and hence will override any duplicates of those properties as well. [block:api-header] { "type": "basic", "title": "modelOptions" } [/block] Allows you to take advantage of `ng-model-options` directive. Formly's built-in templateManipulator (see below) will add this attribute to your `ng-model` element automatically if this property exists. Note, if you use the `getter/setter` option, formly's templateManipulator will change the value of `ng-model` to `options.value` which is a getterSetter that formly adds to field options. For more information on ng-model-options, see [this ng-conf talk](https://www.youtube.com/watch?v=k3t3ov6xHDw) and [these](https://egghead.io/lessons/angularjs-new-in-angular-1-3-ng-model-options-getters-and-setters) [egghead](https://egghead.io/lessons/angularjs-new-in-angular-1-3-ng-model-options-updateon-and-debounce) [lessons](https://egghead.io/lessons/angularjs-new-in-angular-1-3-ngmodeloptions-allows-you-to-set-a-timezone-on-your-model). [block:api-header] { "type": "basic", "title": "noFormControl (boolean)" } [/block] Used to tell angular-formly to not attempt to add the `formControl` property to your object. This is useful for things like validation, but not necessary if your "field" doesn't use `ng-model` (if it's just a horizontal line for example). Defaults to undefined. [block:api-header] { "type": "basic", "title": "watcher (object|array of watches)" } [/block] [Example](http://angular-formly.com/#/example/field-options/watchers) An object which has at least two properties called `expression` and `listener`. The `watch.expression` is added to the `formly-form` directive's scope (to allow it to run even when `hide` is true). You can specify a type (`$watchCollection` or `$watchGroup`) via the `watcher.type` property (defaults to `$watch`) and whether you want it to be a deep watch via the `watcher.deep` property (defaults to `false`). [block:callout] { "type": "warning", "title": "Not a normal watch/formly expression", "body": "This differs slightly from a normal `$watch` function in very useful ways. See [Formly Expressions](doc:formly-expressions) for more information." } [/block] [block:api-header] { "type": "basic", "title": "validators (object)" } [/block] [Example](http://angular-formly.com/#/example/intro/codementor) | [Lesson](https://egghead.io/lessons/angularjs-angular-formly-custom-validation?pl=7) An object where the keys are the name of the validator and the values are [Formly Expressions](doc:formly-expressions) (can be a string or a function) A validator passes if it returns true. A validator fails if it returns false. # Angular < 1.3 Formly defaults to use the `$validators` api, which is only available in angular 1.3. If you are using 1.2, then the `$parsers` api is used which doesn't support async validation out of the box. However, formly will keep track of the validations for you and ensure that the most recently resolved/rejected promise is what takes priority. Also, while the validation is in flight, formly emulates the `$pending` api of 1.3 for your use in 1.2 as well, so you can safely use this and upgrade to 1.3 without worrying about the upgrade path for this api. You're welcome :-) [block:api-header] { "type": "basic", "title": "asyncValidators (object)" } [/block] [Example](http://angular-formly.com/#/example/other/unique-value-async-validation) Use this one for anything that needs to validate asynchronously. Pretty much exactly the same as the `validators` api, except it must be a function that returns a promise. A validator passes if it returns a promise that is resolved. A validator fails if it returns a promise that is rejected. [block:callout] { "type": "info", "body": "You can alternatively specify a validator as an object with an `expression` and a `message`. This will unify how templates reference messages for when the validator has failed. Also, this should be used only for one-off messages (use `ng-messages-include` for generic messages). `message` in this case should be an expression that is evaluated in exactly the same way a validator is evaluated. The `formly-custom-validation` directive will then add an object to the field options called `validation.messages` which is a map of functions where the key is the validation name and the value is a to function which returns the evaluated message. This is especially useful when using `ng-messages`.", "title": "Validator as an object" } [/block] [block:api-header] { "type": "basic", "title": "validation (object)" } [/block] An object with a few useful properties mostly handy when used in combination with ng-messages # validation.messages A map of [Formly Expressions](doc:formly-expressions) mapped to message names. This is really useful when you're using `ng-messages` like in [this example](http://angular-formly.com/#/example/advanced/validators). # validation.show A boolean you as the developer can set to specify to force `options.validation.errorExistsAndShouldBeVisible` to be set to true when there are `$errors`. This is useful when you're trying to call the user's attention to some fields for some reason. See [this example](http://angular-formly.com/#/example/other/force-show-error) # validation.errorExistsAndShouldBeVisible This is set by angular-formly. This is a boolean indicating whether an error message should be shown. Because you generally only want to show error messages when the user has interacted with a specific field, this value is set to true based on this rule: `field invalid && (field touched || validation.show)` (with slight difference for pre-angular 1.3 because it doesn't have touched support). [block:callout] { "type": "info", "title": "showError - shortcut", "body": "Because `options.validation.errorExistsAndShouldBeVisible` is really long, template authors can use `showError` instead which is simply a shortcut for this property." } [/block] [block:api-header] { "type": "basic", "title": "parsers (array of formlyExpressions)" } [/block] This allows you to hook into the [`$parsers`](https://docs.angularjs.org/api/ng/type/ngModel.NgModelController#$parsers) functionality of angular [block:api-header] { "type": "basic", "title": "formatters (array of formlyExpressions)" } [/block] This allows you to hook into the [`$formatters`](https://docs.angularjs.org/api/ng/type/ngModel.NgModelController#$formatters) functionality of angular [block:api-header] { "type": "basic", "title": "value (getter/setter function)" } [/block] This is a getter/setter function for the value that your field is representing. Useful when using `getterSetter: true` in the `modelOptions` (in fact, if you don't disable the `ngModelAttrsTemplateManipulator` that comes built-in with formly, it will automagically change your field's `ng-model` attribute to use `options.value`. --- [block:api-header] { "type": "basic", "title": "All properties below are added" } [/block] So you should not be setting them yourself. [block:callout] { "type": "info", "title": "Added Properties", "body": "The properties listed below are added to your field configuration." } [/block] [block:api-header] { "type": "basic", "title": "formControl (NgModelController)" } [/block] This is the [NgModelController](https://docs.angularjs.org/api/ng/type/ngModel.NgModelController) for the field. It provides you with awesome stuff like `$errors` :-) [block:callout] { "type": "info", "body": "For template authors, a shortcut is provided on the `$scope` for this property called `fc`", "title": "fc - shortcut" } [/block] [block:api-header] { "type": "basic", "title": "initialValue (any)" } [/block] Used in combination with `resetModel` and `updateInitialValue`. Basically, this is set to the value this field represents at compile time, or the last time `updateInitialValue` is called. [block:api-header] { "type": "basic", "title": "resetModel (function)" } [/block] Will reset the field's model and the field control to the last `initialValue`. This is used by the [formly-form](doc:formly-form)'s `options.resetModel` function. [block:api-header] { "type": "basic", "title": "updateInitialValue (function)" } [/block] Will reset the field's `initialValue` to the current state of the model. Useful if you load the model asynchronously. Invoke this when the model gets set. This is used by the [formly-form](doc:formly-form)'s `options.updateInitialValue` function. [block:api-header] { "type": "basic", "title": "runExpressions (function)" } [/block] It is not likely that you'll ever want to invoke this function. It simply runs the `expressionProperties` expressions. It is used internally and you shouldn't have to use it, but you can if you want to, and any breaking changes to the way it works will result in a major version change, so you can rely on its api. [block:html] { "html": "<hr />\n<a href=\"https://app.codesponsor.io/link/PKGFLnhDiFvsUA5P4kAXfiPs/formly-js/angular-formly\" rel=\"nofollow\"><img src=\"https://app.codesponsor.io/embed/PKGFLnhDiFvsUA5P4kAXfiPs/formly-js/angular-formly.svg\" style=\"width: 888px; height: 68px;\" alt=\"Sponsor\" /></a>\n" } [/block]