Telephone Styling

Style every visual detail of the Telephone option type: the country picker beside the number, the searchable country list it opens, the field, its label and help text, the colors it takes while a customer types, and how it looks when validation fails. You do this with per-type templates.

Overview

Read Types Settings first if you haven't created a template before. This page covers every setting available once you're editing a Telephone template, grouped the same way they appear in the editor's left navigation: Country picker, Field style, Label & help text, Field colors, Text, and Focus, error & disabled.

A Telephone template is built on the Short Text template. The field, label, help text, colors, text and focus settings have the same names and defaults. What's new is the country picker: a button with the country's flag and calling code, sitting beside the number, which opens a searchable list of countries. As with Short Text, the template's Help text display replaces the store-wide Help Text Display Mode for every option using it.

A template turns on the country picker and changes what's saved

A Telephone option on Global styles is a plain phone field, and the cart gets the number exactly as the customer typed it. Once you assign any Telephone template, the option gets a country picker (Attached unless you choose otherwise), and the cart gets the calling code in front of the number, e.g. +387 61 234 567. To style the field but keep the plain field and the as-typed value, set Country picker to None. See What the cart line shows.

Three states, not two

A text field has nothing to select, so its third state is focus: the field the customer is currently typing in. Background, border and text color are set separately for Idle, Hover and Focused.

A new template starts from your shop's theme. The idle colors and sizes come from your Colors and Borders & Shapes, and hover and focus colors are worked out from them, so the three states never look identical out of the box. Button background and the country list's Highlighted row start as a light tint of your input background. The hex values in the tables below are what a template uses when your theme doesn't set that color.

Telephone has its own templates

Short Text and Telephone are styled separately. A Telephone option only offers Telephone templates, and a Short Text template never affects a phone field.

What's different from Short Text

If you've already styled Short Text, this is what changes:

Short Text setting	On Telephone
Text alignment	Not offered
Field style, Corners, Border width, Shadow	With Attached, they style the whole row: country button and number together. With Connected or Separate, the button is a box of its own and takes them too
Border color (Hover)	With Connected or Separate, also the button's border under the cursor
Font size, Font weight, Mobile font size	Also apply to the calling code on the country button. Font size also sets the text in the country list. Letter spacing applies to the number only
Error color	With Connected or Separate, also the button's border on the Outlined and Underline styles
(none)	New: the Country picker group, with its Country picker and Country list sections, at the top of the left navigation

Everything else (label, help text, the Idle, Hover and Focused colors, the focus ring and disabled opacity) works exactly as on Short Text.

Country Picker

Two sections in one pane: the button beside the number, and the list it opens. Pick the Country picker style first, since it decides which other settings appear and how the rest of the template is applied.

Country Picker

Setting	Options (default)	What it controls
Country picker	Picture cards: Attached (default) / Connected / Separate / None	How the country button and the number box sit together, or whether there's a button at all
Button shows (Attached, Connected, Separate)	Picture cards: Flag + code (default) / Flag / Code	What's on the country button
Flag shape (Button shows Flag + code or Flag)	Picture cards: Rectangle / Rounded (default) / Circle	The shape of every flag, on the button and in the country list
Button background (Connected, Separate)	Color (worked out from your theme; #F3F4F6)	The country button's fill
Code and arrow color (Attached, Connected, Separate)	Color (your theme input text color; #111827)	The calling code and the arrow on the country button

In-app help:

• Country picker: How the flag and calling code sit beside the number.
• Button background: The country button's fill, where it is a box of its own.
• Code and arrow color: The calling code and the dropdown arrow on the country button.

With None, the other settings in this section are hidden and the editor shows a note instead: No country picker: customers type the whole number, as in a plain phone field.

What each Country picker looks like

Country picker	The box	Between the button and the number	Corners
Attached	One field holds both the button and the number	A short divider line, in the Idle Border color. There's no divider on Underline	Round the whole field
Connected	Two boxes joined edge to edge, like a button group. The button has its own Button background	Outlined: one shared border line. Filled: a hairline gap. Underline: one unbroken line	Only the outer corners: left of the button, right of the number
Separate	Two boxes side by side with a small gap. The button has its own Button background	An 8px gap	Every corner of both boxes
None	No button, just the number field, the same as Short Text	—	Round the field

Button shows decides what's on the button. Flag leaves the calling code off the button, though the list still shows each country's code. Code removes flags everywhere, including the list, which is why Flag shape is hidden for it. Every button ends with a small arrow.

Circle flags aren't cropped

Circle uses square versions of the flags, so a wide flag isn't cut down to its middle. Rounded gives the usual rectangle with softened corners.

On the Underline field style, the button has no fill, so Button background has no visible effect there. On Filled, the button has no border, like the field.

Country List

The list customers pick their country from. It applies only while there's a country picker. With None, the Country list section stays in the left navigation, greyed out, with the note: Choose a Country picker style other than None to style the country list. Your list settings are kept and come back when you pick another style.

Setting	Options (default)	What it controls
Search box	Toggle (on)	Whether the list has a search box at the top
Search placeholder (Search box on)	Text, up to 60 characters (Search country)	The hint in the empty search box
No results message (Search box on)	Text, up to 80 characters (No countries found)	What the list shows when a search matches nothing
Background	Color (your theme input background; #FFFFFF)	The list panel's fill
Text color	Color (your theme input text color; #111827)	Country names and the text typed in the search box
Highlighted row	Color (worked out from your theme; #F3F4F6)	The fill of the row the customer is on
Border color	Color (your theme input border; #D1D5DB)	The panel's border, and the line under the search box
Max height	Slider, 160–440px in steps of 20 (280px)	How tall the list of countries gets before it scrolls. The search box sits above it

In-app help:

• Search box: Lets customers find their country by typing its name or calling code.
• Highlighted row: The row under the pointer, or picked with the arrow keys.

Each row shows the flag (unless Button shows is Code), the country name, and its calling code in a lighter shade of Text color. The country currently picked is bold, with a check mark. The No results message uses the same lighter shade.

The parts of the list you don't set follow the rest of the template. The panel's corners follow Corners: Pill gives 16px, and Custom is capped at 16px. On Underline, the corners follow your store's corner radius. The text uses Font size. When the search box has focus, a line under it shows in the Focus ring color. The panel's drop shadow is fixed.

Search placeholder and No results message aren't translated

Both are shown exactly as you type them, whatever language the shopper is browsing in. The country names do follow the shopper's language. Clear either field and the default English text is used.

Styling the open list

To see the list while you style it, click the country button in the Live Preview. In Style Settings the list stays open while you change settings beside it. It closes when you click the button again, press Escape, or pick a country. In the app's previews the list opens in place and pushes the content below it down, but on your storefront it opens over the page, just below the field.

Field Style

Setting	Options (default)	What it controls
Field style	Picture cards: Outlined (default) / Filled / Underline	The overall look of the field
Corners (Outlined, Filled)	Picture cards: Global (default) / Pill / Square / Custom	Corner rounding
Corner radius (Custom corners only)	Number, 0–40px (6px)	Exact corner rounding
Spacing	Picture cards: Comfortable (default) / Compact	The field's padding and height together
Border width (Outlined, Underline)	Slider, 0–4px (1px, from your theme border width)	Border thickness. On Underline, the thickness of the line
Shadow (Outlined, Filled)	Dropdown: None (default, from your theme input shadow) / Subtle / Medium / Strong	Drop shadow

In-app help:

• Field style: Outlined draws a border around the field. Filled is a tinted box with no border, so the border settings are hidden. Underline draws only a bottom line on a transparent field, so corners, shadow and the background colors are hidden.
• Corners: Global uses your store's corner radius, so it looks square when that radius is 0 — pick Pill, Square or Custom for a specific shape.
• Spacing: Sets the field's padding and height together. Compact suits forms with many fields.
• Border width: On the Underline style this is the thickness of the line.

How Field style combines with the Country picker

	Attached	Connected and Separate
Field style, Border width, Corners, Shadow	One field around the button and the number	Applied to both boxes: the button and the number
Outlined	One border around the whole row	A border around each box. Connected boxes share the line between them
Filled	One tinted box. The button sits on the field's fill	Two tinted boxes. The button uses Button background
Underline	One line under the row. The flag and code sit at the start of the line, with no divider	A line under each box

"Global" corners can look square

Global follows your store's corner radius from Borders & Shapes, so if that radius is 0, the field renders square. Pick Pill, Square or Custom when you want a specific shape regardless of the global value.

Label & Help Text

Two sections in one pane: where the label sits, and how the option's help text is presented.

Label

Setting	Options (default)	What it controls
Label position	Picture cards: Above (default) / Left	Where the label sits relative to the field
Label width (Left only)	Number, 60–320px (140px)	Width of the label column
Space between label and field	Slider, 0–24px (4px)	Gap between the two
Label size	Number, 10–28px (16px)	Label text size
Label weight	Regular / Medium / Semibold (default) / Bold	Label text weight
Label color	Color (your theme text color; #1F2937)	Label color

In-app help for Label position: Left places the label beside the field on wide screens; on phones it stacks above the field.

Left labels stack when there isn't room

Left puts the label beside the field only when there's room. It stacks above the field on screens 768px wide and below. It also stacks in a narrow column on a wide screen, once the option is narrower than your Label width plus Space between label and field plus 230px for the field (160px with Country picker None). If you use Left, set the same Label width on every Telephone option so their fields line up.

Help Text

Setting	Options (default)	What it controls
Help text display	Picture cards: Above field (default) / Below field / Tooltip / Hidden	How the option's help text is shown

In-app help: Replaces the store-wide Help Text Display Mode for options using this template. Tooltip shows an "i" beside the label that reveals the help text on hover.

Shown for Above field and Below field:

Setting	Options (default)	What it controls
Help text color	Color (your theme text color; #4B5563)	Help text color
Help text size	Number, 10–20px (14px)	Help text size
Help text style	Dropdown: Italic (default) / Regular	Help text style

Shown for Tooltip:

Setting	Options (default)	What it controls
Icon color	Color (your theme text color; #6B7280)	The "i" beside the label
Tooltip position	Picture cards: Top (default) / Bottom	Whether the bubble opens above or below the "i"
Tooltip background	Color (#1F2937)	Bubble fill
Tooltip text	Color (#FFFFFF)	Bubble text color
Tooltip text size	Number, 10–18px (14px)	Bubble text size
Tooltip max width	Slider, 120–400px (250px)	Widest the bubble gets before the text wraps

In-app help for Icon color: The "i" beside the label. On hover it fills with the tooltip colors.

Shown for Hidden: no settings, just a note: Options using this template show no help text, even when the option has some.

Help text display overrides your store-wide setting

This is the one setting here that changes what shows, not just how it looks. For every Telephone option using this template, it replaces the store-wide Help Text Display Mode.

With Hidden, no help text appears on those options at all, even when the option has some. The text stays saved; it just isn't shown.

Telephone options with no template assigned keep following the store-wide setting, as before.

Field Colors

Placeholder is set once. Background, Border and Text are set separately for Idle, Hover and Focused (while the customer is typing), each under its own heading.

Setting	Options (default)	What it controls
Placeholder	Color (your theme placeholder color; #6B7280)	The hint shown in the empty number box. All field styles
Background, Idle (Outlined, Filled)	Color (your theme input background; #FFFFFF)	Field fill at rest
Border, Idle (Outlined, Underline)	Color (your theme input border; #D1D5DB)	Border, or underline, color at rest
Text, Idle	Color (your theme input text color; #111827)	The typed number at rest
Background, Hover (Outlined, Filled)	Color (worked out from your theme; #F9FAFB)	Field fill under the cursor
Border, Hover (Outlined, Underline)	Color (worked out from your theme; #9CA3AF)	Border, or underline, color under the cursor
Text, Hover	Color (your theme input text color; #111827)	The typed number under the cursor
Background, Focused (Outlined, Filled)	Color (your theme input background; #FFFFFF)	Field fill while the customer types
Border, Focused (Outlined, Underline)	Color (worked out from your theme; #2563EB)	Border, or underline, color while the customer types
Text, Focused	Color (your theme input text color; #111827)	The typed number while the customer types

In-app help:

• Placeholder: The hint shown in the empty field.
• Border (Focused): Shown while the customer is typing. The focus ring itself is set under Focus, error & disabled.

Hover colors start as your theme's input colors shifted toward your text color, and the focused border is shifted toward your button color. The focused field keeps its resting background, as on Short Text. The typed number keeps your theme's input text color in all three states so it stays readable.

Where the colors go:

Country picker	Background, Border and Text
Attached	The whole row. Hovering anywhere on it shows the Hover background and border. While the customer is in the number box, or on the country button, the whole row takes the Focused background and border. The button area tints slightly on hover
Connected, Separate	The number box. The button keeps Button background and the Idle Border. On hover its border takes the Hover Border color and its fill tints slightly
None	The field, as on Short Text

The calling code and arrow use Code and arrow color, not Text.

Text

How the number the customer types is rendered.

Setting	Options (default)	What it controls
Font size	Number, 10–28px (14px)	Size of the typed number and the calling code on the button. The country list uses it too
Font weight	Regular (default) / Medium / Semibold / Bold	Weight of the typed number and the calling code on the button
Letter spacing	Number, −1 to 4px in steps of 0.5 (0px)	Spacing between the characters of the typed number. The calling code keeps normal spacing
Mobile font size	Number, 10–24px (empty, which uses Font size)	Replaces Font size for the number and the calling code at 768px wide and below

In-app help for Mobile font size: Optional override at 768px wide and below. Leave empty to use the same size everywhere.

The country list keeps Font size on phones too.

Focus, Error & Disabled

Setting	Options (default)	What it controls
Focus ring	Toggle (on)	Whether a ring is drawn around the field the customer is typing in
Focus ring color (Focus ring on)	Color (your theme button color; #2563EB)	Ring color
Focus ring width (Focus ring on)	Slider, 1–5px (2px)	Ring thickness
Error color	Color (#DC2626)	The message under the field, and the field's border, when validation fails
Disabled opacity	Slider, 10–100% (50%)	How faded the number box and country button look when the theme disables them

In-app help:

• Focus ring: The ring shown while the field is focused. On the Underline style it is drawn as a thicker line. Turning it off leaves only the focus border color to show which field is active.
• Error color: Applies to the message under the field and to the field's border when validation fails. Turn on Show error state in Manage preview to see it.

Where the focus ring is drawn:

Country picker	While the customer types the number	On the country button, reached with the keyboard
Attached	Around the whole row, with a small gap	Just inside the field's edge, around the button
Connected, Separate	Around the number box, with a small gap	Around the button, with a small gap
None	Around the field, with a small gap	—
Any style with Underline	A thicker line under the field, in the ring color	Around the button, with a small gap

With Focus ring off, a button reached with the keyboard still shows its hover tint, so customers can see where they are.

What a failed field looks like:

Country picker	Outlined	Filled	Underline
Attached	The row's border in the Error color	A thin ring in the Error color around the row	The row's underline in the Error color
Connected, Separate	The borders of both the number box and the button in the Error color	A thin ring in the Error color around the number box	Both underlines in the Error color
None	The field's border in the Error color	A thin ring in the Error color	The underline in the Error color

A failed field keeps its Idle background on hover. The message under it always uses the Error color.

Seeing the error state

You don't have to fail an Add to cart on a live storefront to style the error look: in Manage preview, turn on Show error state. See Sandbox & Live Preview.

Turning the focus ring off

With the ring off, the only thing marking the active field is the Focused border color from Field colors. Make sure that color is clearly different from Idle, or customers won't be able to tell which field they're in.

On the Storefront

The country picker and list

Clicking the country button opens the list just below the field, over the content beneath it. The list holds about 240 countries and territories, named in the shopper's storefront language and sorted alphabetically in that language. When it opens, the current country is highlighted and scrolled into view. Picking a country closes the list and moves the cursor to the number box, the next thing to fill in. Clicking outside the list closes it without a change.

Flags are small images, loaded as they come into view. While one loads, or if it can't load, a light grey box stands in for it.

Searching

With Search box on, the cursor goes straight to the search box when the list opens, and the list narrows as the customer types. A search matches:

• the start of any word in the country name, ignoring case and accents: bos or herz finds Bosnia and Herzegovina
• the two-letter country code: ba
• the calling code, with or without the plus: 387 or +387

Enter picks the highlighted row: the first match, unless the current country is still among the matches. When nothing matches, the list shows your No results message.

With Search box off, the list itself takes focus, and typing the first letters of a country jumps to it.

Which country it starts on

The picker starts on the country your storefront is showing the shopper: their market country, the one your country/region selector is set to. If that isn't available, it uses the region in the shopper's browser language, and then the United States.

What the cart line shows

Nothing is saved while the number box is empty. Picking a country on its own doesn't fill in the option, so a required Telephone still blocks Add to cart until the customer types a number, and an optional one left empty adds nothing to the cart line.

Once there's a number, this is what the cart line shows, for an option labelled Phone number:

Option uses	Customer enters	Cart line
A template with a country picker (Attached, Connected, Separate)	Bosnia and Herzegovina, then 61 234 567	Phone number: +387 61 234 567
A template with Country picker None	061 234 567	Phone number: 061 234 567
Global styles (no template)	061 234 567	Phone number: 061 234 567

With a country picker, the saved value is a plus, the calling code, a space, then the number exactly as typed. Spaces, dashes and brackets are kept, and so is a leading 0: a customer who types 061 234 567 saves +387 061 234 567. If the customer types a number that starts with a calling code the list doesn't recognize, it's saved as typed.

Set a placeholder that matches the picker

The option's own Placeholder shows in the number box (Enter phone number if it has none). With a country picker, show the number without its country code, e.g. 61 234 567, so customers don't type the code twice.

Pasting a full international number

With a country picker, a customer can paste or type a full number such as +44 20 7946 0958. The picker switches to United Kingdom and the box keeps only 20 7946 0958.

While the customer is still typing a code (+, +4, +44), the box shows exactly what they typed. It switches once the first digit of the number follows. If they pick a country from the list instead, the code they typed is replaced.

Some calling codes are shared by several countries, such as +1, +7 and +44. For those, the picker keeps the current country if it uses that code; otherwise it picks the code's main country, e.g. United States for +1.

Required and errors

After a failed Add to cart, the field takes the error look described in Focus, error & disabled and shows a message under it in the Error color:

• A required field left empty shows your store's required message, e.g. Phone number is required. See Language Settings.
• A number with fewer than six digits, or with letters in it, shows Please enter a valid phone number.

The error clears as soon as the customer types in the field or picks a country.

Editing from the cart

When a customer edits the line from the cart, the field reopens with the saved country and number: +387 61 234 567 comes back as Bosnia and Herzegovina and 61 234 567. For a shared calling code, the picker shows the shopper's starting country if it uses that code, otherwise the code's main country. The saved number is the same either way.

Keyboard

Key	On the country button	In the open list
Enter or Space	Opens or closes the list	Enter picks the highlighted country
↓ / ↑	Opens the list	Moves the highlight one row
Page Down / Page Up	—	Moves the highlight eight rows
Home / End	—	First or last country. With a search box, these move the cursor in the box instead
Escape	—	Closes the list and puts focus back on the country button
Tab	Moves on to the number box	Closes the list and moves on

After a country is picked, the cursor moves to the number box.

Phones and narrow columns

• The number box brings up the phone keypad.
• Mobile font size, when set, replaces Font size for the number and the calling code at 768px wide and below.
• A Left label stacks above the field at 768px wide and below, and in any column too narrow for the label and a usable phone field (see Label).
• The country list is as wide as the field and at least 280px, but never wider than the screen.

Options without a template

Telephone options on Global styles look and save exactly as they did before templates existed: a plain phone field with your theme's input colors, no country picker, the number saved exactly as typed, and help text following the store-wide Help Text Display Mode. If an option's template is deleted, the option goes back to Global styles.

How to Style Telephone

1. Open the Style Settings modal (see Customization Overview)
2. Click Types → Telephone
3. Create a new template or click an existing one to edit it
4. Use the left navigation to jump between Country picker, Field style, Label & help text, Field colors, Text, and Focus, error & disabled
5. Pick a Country picker first. It decides whether Button shows, Flag shape, Button background, Code and arrow color and the whole Country list section apply
6. To style the list, click the country button in the Live Preview. It stays open while you change the Country list settings
7. In Field colors, set Background, Border and Text under the Idle, Hover and Focused headings
8. Click Manage preview to put your own label, placeholder and help text in the preview, or to see the error state. See Sandbox & Live Preview
9. Click Save in the contextual save bar

Assign the template on the option itself: open a Telephone option, click Style Settings, and pick a template card (or Global styles). Then save the option set. Remember that assigning a template is what gives the option its country picker and changes what's saved to the cart. See What the cart line shows.

Related

• Telephone (option type): how to add and configure a Telephone option
• Types Settings: how templates work and how to assign one to an option
• Sandbox & Live Preview: build a test field and preview the error state
• Help Text Display Mode: the store-wide setting this template can override
• Language Settings: the message shown under a required field left empty
• Short Text Styling: the template this one is built on
• Accordion Styling
• Checkbox Styling
• Radio Styling
• Swatches Styling
• Tabs Styling
• File Upload Styling
• Slider Styling
• Date Range Styling
• Time Picker Styling
• Modal Styling
• Short Text Group Styling
• Formula Styling
• Number Styling