Form Field
A single form input field. Use inside a Canvas Form to collect user input. It is shown in the block inserter as Form Field and registered as canvas-core/form-field.
Select the block on a page and its own settings open in the sidebar, in the panels below:
Settings
Each setting is named exactly as the block editor names it, followed by what it does and what it starts as. Where a setting carries a Shown when line, it stays hidden until that condition is met, which is the usual reason a setting looks missing from the sidebar:
Field
Field TypeDefaultText
What kind of answer this field collects. It decides which control the visitor sees and which of the settings below are read, so choose it first. Some choices are not questions at all: Section Divider, Notice and Step Break shape the form, and the last four guard it against robots.
ChoicesTextEmailSearchTextareaSelect / DropdownRadio ButtonsCheckbox GroupImage SelectNumberURLTelephoneDateand 21 more
Field Name (key)DefaultEmpty
Used as the form submission key. Must be unique within the form. A few names are reserved; the editor says so if you pick one.
Field ID (exact)DefaultEmpty
An exact name for this control in the page. Leave it empty and Canvas works one out from the field name, adding a suffix when the same form appears twice. Set it when a design or a script has to find this field by name; the label and everything else that points at the control follow whatever you enter.
Single Bare ControlDefaultOff
Emit ONE bare input and nothing else (no option list, no wrapper) so a design can build its own clickable card, .form-check row or switch around it. The Default Value below is what this control submits.
Shown when Field Type is "Radio Buttons" or "Checkbox Group"
Selected by DefaultDefaultOff
Starts this control already ticked, which is how one option in a set is offered as the recommended one.
Shown when Single Bare Control is on
Posts as Array (single control)DefaultOff
Render the single control's name as name[] so several controls sharing one key post together, the same shape the option-list checkbox group already uses.
Shown when Single Bare Control is on
autocomplete="off"DefaultOff
Stops the browser restoring a previous choice on reload, what a plan picker wants.
Shown when Single Bare Control is on
UI-Only Control (no name)DefaultOff
Stops this control submitting anything. Some checkboxes are not questions at all: a colour scheme switch, a show grid toggle, a filter pill. They exist so the design can draw a state, and a control like that would otherwise post a meaningless answer with every form it sits inside.
Shown when Single Bare Control is on
LabelDefaultEmpty
The question above the field. It is what names the control for a screen reader, so fill it in even where the design hides it.
PlaceholderDefaultEmpty
The faint prompt inside the empty field, which disappears as soon as the visitor types. Use it for an example answer, never in place of the label.
RequiredDefaultOff
Stops the form being sent until this field is answered. Ask only for what you genuinely need, since every required field costs you entries.
Default ValueDefaultEmpty
An answer the field starts with. The visitor can change it, and it is submitted as it stands if they do not.
Help TextDefaultEmpty
A short note under the field, for saying why you are asking or what a valid answer looks like.
Step TitleDefaultEmpty
Label shown for this step in multi-step navigation.
Shown when Field Type is "Step Break (multi-step)"
Consent TextDefaultEmpty
The sentence shown beside the checkbox: this is what names the control for screen readers. Inline HTML is kept, so the terms/privacy link can sit inside the sentence.
Shown when Field Type is "Consent / GDPR Checkbox"
Checked by DefaultDefaultOff
Pre-ticks the box. Leave off for GDPR-style consent, which has to be given actively.
Shown when Field Type is "Consent / GDPR Checkbox"
Notice ContentDefaultEmpty
Message shown in the notice. Inline HTML (links, ) is kept.
Shown when Field Type is "Notice / Info Block"
Notice StyleDefaultInfo
What the notice is telling the visitor, which decides its colour: an aside, a confirmation, a caution or a problem.
ChoicesInfoSuccessWarningErrorShown when Field Type is "Notice / Info Block"
DismissibleDefaultOff
Adds a close button that hides the notice.
Shown when Field Type is "Notice / Info Block"
Divider LabelDefaultEmpty
Optional caption for the separator. The caption sits at the start of the row and the rule fills the space after it; leave it empty for a plain full-width rule.
Shown when Field Type is "Section Divider"
Divider StyleDefaultSolid
Line style of the rule, with or without a caption.
ChoicesSolidDashedDottedShown when Field Type is "Section Divider"
Options (one per line)DefaultEmpty
One option per line. For key/value pairs use: key|Label. For typeahead fields, each line is one autocomplete suggestion.
Shown when Field Type is "Select / Dropdown" or "Radio Buttons" or "Checkbox Group" or "Select Picker" or "Select Box" or "Typeahead / Autocomplete"
Options Come FromDefaultThe list above
Terms are read live, so a term added later appears in the field with no edit here. A hierarchical taxonomy renders its top-level terms as option groups.
ChoicesThe list aboveA taxonomy's termsShown when Field Type is "Select / Dropdown" or "Radio Buttons" or "Checkbox Group" or "Select Picker" or "Select Box"
TaxonomyDefaultEmpty
Each option carries the term slug as its value, so the results page can query it directly.
Choices- Select a taxonomy - (empty)Category (category)Tag (post_tag)Brand (product_brand)Category (product_cat)Tag (product_tag)Shipping class (product_shipping_class)Portfolio Category (canvas_portfolio_category)Event Category (canvas_event_category)Shown when Options Come From is "A taxonomy's terms"
First Option LabelDefaultEmpty
A leading option with an empty value, the "no filter" choice. Leave empty to list only the terms.
Shown when Options Come From is "A taxonomy's terms"
Image OptionsDefaultEmpty
One row per selectable image.
Shown when Field Type is "Image Select"
Each row of Image Options takes:
ImageDefault
0The picture a visitor picks, chosen from your media library.
CaptionDefaultEmpty
The wording under this picture, which is what names the choice for a screen reader.
Submitted ValueDefaultEmpty
Value sent with the form. Falls back to the caption when empty.
ColumnsDefault3 Columns
How many pictures sit across a row of the choices.
Choices2 Columns3 Columns4 Columns5 ColumnsShown when Field Type is "Image Select"
Allow MultipleDefaultOff
Renders checkboxes instead of radio buttons so several images can be picked.
Shown when Field Type is "Image Select"
RowsDefault
5How many lines of the message box are visible at once, which is how you set its height without any styling of your own. Set 0 when a stylesheet already gives the box its height.
Shown when Field Type is "Textarea"
Minimum ValueDefaultEmpty
The lowest number the visitor may enter. Anything below it is refused before the form is sent.
Shown when Field Type is "Number" or "Range Slider"
Maximum ValueDefaultEmpty
The highest number the visitor may enter.
Shown when Field Type is "Number" or "Range Slider"
StepDefaultEmpty
How far the value moves with each nudge, and what counts as a valid figure. Set it to 0.01 to allow pence, or 5 to accept multiples of five only.
Shown when Field Type is "Number" or "Range Slider"
Code LengthDefault
6Number of single-character code boxes.
Shown when Field Type is "OTP / One-Time Code"
Bordered BoxesDefaultOff
Thicker-border style for the code boxes.
Shown when Field Type is "OTP / One-Time Code"
Minimum CharactersDefault
1Characters typed before suggestions appear.
Shown when Field Type is "Typeahead / Autocomplete"
Allowed File TypesDefault
jpg,jpeg,png,gif,pdfComma-separated extensions, without the dot. Starts from the site default in Theme Options → Forms.
Shown when Field Type is "File Upload"
Max File Size (MB)Default
5Per-file limit enforced by the upload script. Starts from the site default in Theme Options → Forms.
Shown when Field Type is "File Upload"
Max FilesDefault
1More than one turns the control into a multi-file input.
Shown when Field Type is "File Upload"
Drag & Drop ZoneDefaultOff
Adds a drop area above the file input.
Shown when Field Type is "File Upload"
Show/Hide ToggleDefaultOff
Adds an eye button that toggles password visibility.
Shown when Field Type is "Password"
Confirm Password FieldDefaultOff
Adds a second field that must match the password.
Shown when Field Type is "Password"
Strength MeterDefaultOff
Shows a live weak/medium/strong bar under the field.
Shown when Field Type is "Password"
Earliest DateDefaultEmpty
YYYY-MM-DD. The Date Picker also accepts relative values such as 0d (today) or +1m.
Shown when Field Type is "Date" or "Date Picker"
Latest DateDefaultEmpty
YYYY-MM-DD. The Date Picker also accepts relative values such as +30d.
Shown when Field Type is "Date" or "Date Picker"
Earliest TimeDefaultEmpty
The earliest time a visitor may choose, written as hours and minutes. Set it to the hour you open.
Shown when Field Type is "Time"
Latest TimeDefaultEmpty
The latest time a visitor may choose, written as hours and minutes.
Shown when Field Type is "Time"
Time Step (minutes)Default
15Interval the time picker steps through.
Shown when Field Type is "Time"
Date FormatDefault
mm/dd/yyyyHow a chosen date is written in the field. Match it to the convention your visitors read dates by, since 03/04 means two different days on either side of the Atlantic.
Shown when Field Type is "Date Picker"
Auto Close on SelectDefaultOn
Closes the calendar as soon as a day is picked, rather than leaving it open over the rest of the form.
Shown when Field Type is "Date Picker"
Highlight TodayDefaultOn
Marks the current day in the calendar, so a visitor can see where they are before choosing.
Shown when Field Type is "Date Picker"
Disable Past DatesDefaultOff
Greys out every day before today, which is what a booking or a delivery date needs.
Shown when Field Type is "Date Picker"
Min ValueDefault
0The value at the left hand end of the track.
Shown when Field Type is "Range Slider"
Max ValueDefault
100The value at the right hand end of the track.
Shown when Field Type is "Range Slider"
StepDefault
1How far the handle moves with each nudge. Larger steps make a wide track quick to cross and stop a visitor landing on an awkward figure.
Shown when Field Type is "Range Slider"
Double HandlesDefaultOff
Two-handle range (a from-to interval) instead of a single value.
Shown when Field Type is "Range Slider"
Initial To ValueDefaultEmpty
Starting position of the second handle. Empty starts at the maximum.
Shown when Field Type is "Range Slider" and Double Handles is on
Value PrefixDefaultEmpty
Text before each value bubble, e.g. "$".
Shown when Field Type is "Range Slider"
Value PostfixDefaultEmpty
Text after each value bubble, e.g. " sqm.".
Shown when Field Type is "Range Slider"
Max-Value PostfixDefaultEmpty
Extra text when a handle sits at the maximum, e.g. "+".
Shown when Field Type is "Range Slider"
Show GridDefaultOff
Draws a scale of marks and figures under the track, so a visitor can see the range at a glance rather than dragging to find it.
Shown when Field Type is "Range Slider"
Limits From ContentDefaultOff
Take the ends of the track from the records themselves instead of the Min/Max above, so a record priced outside the typed range can never become unreachable.
Shown when Field Type is "Range Slider"
RecordsDefaultEmpty
The content the limits are measured across.
Choices- Select a content type - (empty)Post (post)Page (page)Product (product)Portfolio Item (canvas_portfolio)Event (canvas_event)Shown when Field Type is "Range Slider" and Limits From Content is on
Value FieldDefaultEmpty
The custom field holding the number, e.g. the numeric price. Values that are not numbers are ignored.
Shown when Field Type is "Range Slider" and Limits From Content is on
Separate Scales ByDefaultEmpty
Optional. A custom field whose value splits the records into scales that are measured separately: rents and sale prices, say, which share a currency and nothing else.
Shown when Field Type is "Range Slider" and Limits From Content is on
Scale ControlDefaultEmpty
Optional. The name of another control in this form that chooses the scale. The track re-scales as the visitor changes it.
Shown when Field Type is "Range Slider" and Limits From Content is on
Starting ScaleDefaultEmpty
Optional. The scale shown before the visitor chooses one. Empty measures every record together.
Shown when Field Type is "Range Slider" and Limits From Content is on
Max StarsDefault
5How many stars the scale offers, and so the best score a visitor can give.
Shown when Field Type is "Star Rating"
Rating StepDefaultFull Star
Whether a visitor can only give whole stars, or half a star as well.
ChoicesFull StarHalf StarShown when Field Type is "Star Rating"
Star SizeDefaultSmall
How large the stars are drawn. Larger stars are easier to hit on a phone.
ChoicesExtra SmallSmallMediumLargeExtra LargeShown when Field Type is "Star Rating"
Live SearchDefaultOff
Adds a search box at the top of the list, which a long list of options needs if a visitor is to find anything.
Shown when Field Type is "Select Picker"
Multiple SelectionDefaultOff
Lets a visitor choose more than one option rather than exactly one.
Shown when Field Type is "Select / Dropdown" or "Select Picker" or "Select Box"
Editor ToolbarDefaultBasic (bold, italic, lists, link)
How much formatting the visitor is offered. Keep it basic for a comment box; a full toolbar invites markup a plain message does not need.
ChoicesBasic (bolditaliclistslink)Standard (adds headingsalignmentcolour)Full (adds mediaindenthighlight)Shown when Field Type is "WYSIWYG / Rich Text"
Editor Height (px)Default
300How tall the editing area is drawn before it scrolls.
Shown when Field Type is "WYSIWYG / Rich Text"
Add Media ButtonDefaultOff
Shows the media library button above the editor. It only works for a visitor who is signed in and allowed to upload.
Shown when Field Type is "WYSIWYG / Rich Text"
Max SelectionsDefault
00 = unlimited
Shown when Field Type is "Select Picker" or "Select Box"
Visible RowsDefaultEmpty
How many options the list shows at once before it starts to scroll.
Shown when Field Type is "Select Picker"
Selection PlaceholderDefaultEmpty
What the closed picker reads before anything has been chosen, such as Any.
Shown when Field Type is "Select Picker"
Picker Button StyleDefault
btn-defaultThe style class the closed picker button takes. Clear it to leave the appearance entirely to your design.
Shown when Field Type is "Select Picker"
On TextDefault
YesThe word shown inside the switch while it is on.
Shown when Field Type is "Switch / Toggle"
Off TextDefault
NoThe word shown inside the switch while it is off.
Shown when Field Type is "Switch / Toggle"
On ColorDefaultSuccess
The colour the switch takes while it is on.
ChoicesPrimaryInfoSuccessWarningDangerDefaultTheme ColorShown when Field Type is "Switch / Toggle"
Switch SizeDefaultDefault
How large the switch is drawn.
ChoicesMiniDefaultLargeShown when Field Type is "Switch / Toggle"
Off ColorDefaultDefault
The colour the switch takes while it is off.
ChoicesPrimaryInfoSuccessWarningDangerDefaultTheme ColorShown when Field Type is "Switch / Toggle"
Value When OnDefaultEmpty
What the switch submits in its ON position.
Shown when Field Type is "Switch / Toggle"
Value When OffDefaultEmpty
A checkbox submits nothing when it is off, so an OFF position that has to mean something needs its own value. Set it and the field submits this instead of nothing.
Shown when Field Type is "Switch / Toggle"
On by DefaultDefaultOff
Renders the switch in its ON position.
Shown when Field Type is "Switch / Toggle"
Style
Label Inline StyleDefaultEmpty
Styling written straight onto the label, usually to adjust the gap between it and the control under it.
Input Group IconDefaultEmpty
Icon shown in a leading .input-group-text box before the control. Needs an Input Wrapper Class of input-group.
Input Group ImageDefaultEmpty
Image shown in the leading box instead of an icon.
Input Group Image Alt TextDefaultEmpty
How that picture is described to someone who cannot see it. Leave it empty where the picture is decoration and the label already says everything.
Shown when Input Group Image is set
Input Group Image WidthDefaultEmpty
How wide that picture is drawn, in pixels. Setting both width and height keeps the row from jumping as the picture loads.
Shown when Input Group Image is set
Input Group Image HeightDefaultEmpty
How tall that picture is drawn, in pixels.
Shown when Input Group Image is set
Input Group Box ClassesDefaultEmpty
Extra classes on the leading .input-group-text box.
Input Group Box ElementDefaultSpan (default)
Element the leading box is built from.
ChoicesSpan (default)Division
Layout
Field WidthDefaultEmpty
Adds a Bootstrap grid column class to the field wrapper (Half = col-md-6, One Third = col-md-4, Two Thirds = col-md-8, Full Width Column = col-12). Columns only take effect inside a row: set the parent Form block's Layout to "Row", or add the class "row" to the group wrapping these fields. Without a row the field stays full width and this setting does nothing.
ChoicesDefault (no column) (empty)One ThirdHalfTwo ThirdsFull Width Column
Field SpacingDefaultOn
Keep the standard gap under this field. Turn it off where the row around the field already supplies the spacing, so the field does not add a second gap.
Wrapper Extra ClassesDefaultEmpty
Optional utility classes appended to the field wrapper element.
Label Extra ClassesDefaultEmpty
Optional utility classes appended to the field label element.
Check MarkupDefaultCanvas
Bootstrap emits .form-check / .form-check-input / .form-check-label so the framework styles the group.
ChoicesCanvasBootstrap (.form-check)Shown when Field Type is "Radio Buttons" or "Checkbox Group"
Inline OptionsDefaultOff
Lays the options in a row across the page rather than one under another. It suits two or three short options and crowds a long list.
Shown when Check Markup is "Bootstrap (.form-check)"
Control Wrapper ClassesDefaultEmpty
Wraps the control (not the label) in an element with these classes: how a horizontal form gives the control its own grid column.
Help Text ClassesDefaultEmpty
Style classes on the help note under the field, usually to set it small and quiet.
Input Extra ClassesDefaultEmpty
Optional utility classes appended to the input / select / textarea element.
Character Width (size)Default
0How wide the field is, counted in characters. Set it to 0 to leave the width to the design instead.
Tab IndexDefaultEmpty
Explicit keyboard order for this control. Leave empty unless the visual order differs from the source order; a positive value takes the field out of the natural sequence for everyone.
Autofill PurposeDefaultEmpty
What this field is for, so a visitor can fill it from details their browser has already saved: name, email, tel, organization, street-address, postal-code and the rest of the HTML autocomplete tokens. Leave empty to say nothing.
Read OnlyDefaultOff
The visitor can read the value and it is still submitted, but they cannot change it. Use it to restate something decided earlier in the journey; a field nobody should submit at all belongs in a Hidden field instead.
Shown when Field Type is "Text" or "Email" or "Search" or "Textarea" or "Number" or "URL" or "Telephone" or "Date" or "Time" or "Password" or "Select / Dropdown"
Bare Input (no Bootstrap class)DefaultOff
Drop the default form-control / form-select class so the Input Extra Classes fully control the appearance. The form JS hook (cnvs-field-input) is kept.
Unwrapped Field (control only)DefaultOff
Render only the input/select/textarea: no field wrapper, label, help text or error placeholder. Needed when the control must be a DIRECT child of a Bootstrap input-group. Native HTML validation and server-side validation still apply; the client-side validation UI is skipped for this field.
Anonymous Control (no name or id)DefaultOff
Leaves the control with no name and no id at all. For a control that is there for the look of it, in a form that goes nowhere, where both would be invented. The control is still named for assistive technology by its accessible label.
Shown when Unwrapped Field (control only) is on and Field Type is "Text" or "Email" or "URL" or "Telephone" or "Number" or "Select / Dropdown" or "Select Picker"
Control Carries an IDDefaultOn
Turn it off to leave the control with no id while it still submits its answer. That suits an unwrapped control with no label of its own, where the id would be pointed at by nothing. The control is still named for assistive technology by its accessible label.
Shown when Unwrapped Field (control only) is on and Anonymous Control (no name or id) is off
Plain Label (unwrapped field)DefaultOff
With Unwrapped Field on, still emit a plain label element right before the control (inline-sentence forms whose labels flow with the controls). Label Extra Classes apply; no other label chrome.
Shown when Unwrapped Field (control only) is on
Plain Label PlacementDefaultBefore the control
Where the plain label sits relative to the control. "After" is the Bootstrap .btn-check contract, where the label is the visible button and must follow its input.
ChoicesBefore the controlBefore the controlon its own lineAfter the controlShown when Plain Label (unwrapped field) is on
No Placeholder Option (select)DefaultOff
Skip the leading empty "- Select -" option so the first authored option (or the Default Value) is pre-selected.
Lock Placeholder OptionDefaultOff
Render the leading placeholder option as disabled and selected, so it shows first but cannot be chosen as an answer.
Shown when Field Type is "Select / Dropdown" and No Placeholder Option (select) is off
Placeholder Option ValueDefaultEmpty
Value attribute on the leading placeholder option. Empty submits an empty string.
Shown when No Placeholder Option (select) is off
Input Inline StyleDefaultEmpty
Styling written straight onto the control itself, such as a maximum width for a field that only ever holds a few characters.
After-Control HTMLDefaultEmpty
Optional inline HTML or text emitted immediately after the control (e.g. the punctuation of an inline-sentence form).
Label PositionDefaultAbove
Where the label sits in relation to the control. Hidden keeps it for screen readers while taking it off the screen, which suits a field whose placeholder already says what it is.
ChoicesAboveBelowInlineHidden (screen-reader only)
Conditional
Enable Conditional LogicDefaultOff
Show or hide this field based on what was entered in another field.
ActionDefaultShow this field if…
Whether the rules below bring this field into view or take it out of it. A field the visitor never saw is neither checked nor stored.
ChoicesShow this field if…Hide this field if…Shown when Enable Conditional Logic is on
MatchDefaultAll rules
Whether every rule has to be met before the action runs, or only one of them.
ChoicesAll rulesAny ruleShown when Enable Conditional Logic is on
RulesDefaultEmpty
One row per rule.
Shown when Enable Conditional Logic is on
Each row of Rules takes:
Field NameDefaultEmpty
The Name of another field in this form.
OperatorDefaultis
How the answer in that field is compared with the value below. The last two need no value of their own.
Choicesisis notcontainsdoes not containstarts withends withis greater thanis less thanis emptyis not empty
ValueDefaultEmpty
What the other answer is compared against. For a set of options, enter the value the option submits rather than the wording a visitor reads.
Style tab
Input Text Color
A style control in the Input group of the Style tab.
Input Background
A style control in the Input group of the Style tab.
Input Border
A style control in the Input group of the Style tab.
Input Radius
A style control in the Input group of the Style tab.
Input Typography
A style control in the Input group of the Style tab.
Focus Border
A style control in the Focus group of the Style tab.
Label Color
A style control in the Label group of the Style tab.
Label Typography
A style control in the Label group of the Style tab.
Related
Every Canvas block also carries the Animation, Scroll Effects and Advanced panels, which are described in Controls every Canvas block has.
Other blocks in Forms: Form, Form Embed, Form Submit Button, Quick Contact.