Skip to main content

Phone Number

Released in version 1.17.0

See the 1.17.0 release notes for more information.

The Phone Number block renders a phone number as a clickable tel: link.

It is designed to be both:

  • Editor-friendly: you can render as a simple link, or as a native Gutenberg Button to use all core Button styling options.
  • Data-friendly: the Phone Number and Label fields accept shortcodes (including common ACF shortcodes).

Fields (supports shortcodes)​

This block provides fields in the block sidebar:

Phone Number​

The phone number used to generate the tel: link.

  • Example: (555) 123-4567
  • Shortcode example: [acf field="phone"]

Label (Optional)​

If provided, this text is used as the visible link/button text instead of the phone number.

  • Example: Call Us
  • Shortcode example: Call [acf field="company_name"]

Render As​

Choose how the block outputs:

  • Text Link: outputs a plain <a href="tel:...">...</a>.
  • Button (native): creates a nested core block structure so you are styling a real Gutenberg Button.

When you use Button (native), the block creates:

  • core/buttons
  • core/button (inside the Buttons block)
Why this matters

All the normal Button settings (styles, colors, typography, border, width, etc.) are available because the inner block is a native core/button.

Default Country Code​

Used only when the Phone Number value does not start with +.

  • Default: +1
  • Example: if you enter 555-123-4567 and Default Country Code is +1, the href becomes tel:+15551234567.

How tel: normalization works​

On the frontend, this block converts the entered phone number into a consistent format for performance and compatibility:

  • Output format: tel:+15555555555 (or tel:+15555555555;89 when an extension is present; see Extensions below)
  • Non-digits are removed.
  • If the number does not start with +, the block prefixes the Default Country Code.
Shortcodes in the editor

The editor cannot evaluate WordPress shortcodes.

If your Phone Number or Label contains shortcodes, the editor preview may show the raw shortcode text. The frontend output will resolve the shortcodes.

Extensions​

If an extension is detected at the end of the phone string, it is appended to the tel: href using this convention:

  • Example input: 555-123-4567 x89
  • Example output: tel:+15551234567;89

Supported patterns include:

  • x89
  • ext 89 / ext. 89
  • extension 89
  • #89

Styling and configuration​

Text Link mode​

Styling is controlled by your theme styles for links.

Button mode​

Because the block contains a native Button, you can configure it normally using the standard Gutenberg UI:

  • Button style (Fill / Outline)
  • Colors
  • Typography
  • Border
  • Spacing
  • Width
  • (and any theme-provided button settings)

Troubleshooting​

The button URL keeps changing back​

This is expected.

When using Button (native), the block forces the nested Button URL to the computed tel: link derived from the Phone Number field.

My shortcode doesn’t render in the editor​

This is expected.

Shortcodes are resolved when WordPress renders the block on the frontend.

Block Bindings (WordPress 6.5+)​

The Phone Number block supports the WordPress Block Bindings API introduced in WordPress 6.5.

Block bindings allow the Phone Number and Label attributes to be connected to an external data source — such as an ACF field provided by a Custom Meta Block — so that the value is resolved dynamically at render time.

How it works​

  1. A binding source (e.g. from the Custom Meta Block plugin) provides a value for the phone or label attribute.
  2. WordPress 6.5+ automatically injects the resolved value into $attributes['phone'] (or $attributes['label']) before the block's render.php is called.
  3. All downstream formatting — tel: URL normalization, extension handling, shortcode processing — runs on the resolved value exactly as it would for a manually entered value.

Editor behaviour​

When an attribute is connected to a binding source:

  • The corresponding input field is disabled (read-only) in the block inspector.
  • An info notice is shown in the inspector explaining that the field is connected.
  • The frontend value will be resolved from the binding source at render time.

MFB Object Path Workaround (No MFB Changes)​

When the Phone Number block is nested inside an MFB object/sub-field context, you can optionally resolve values directly from MFB context paths without changing the MFB plugin.

This is useful when MFB's display UI does not offer a native Phone block target.

New optional settings​

  • MFB Phone Path (Optional)
  • MFB Label Path (Optional)

These fields accept slash-separated paths (for example: group/phone, group/phone_label).

How path resolution behaves​

  1. If a path is set and a value is found in mfb/value, that value is used.
  2. If no value is found, the block falls back to the regular Phone Number / Label attribute values.
  3. Shortcode processing and tel: normalization still run as usual after path resolution.

Editor behaviour with paths​

  • The regular Phone Number or Label input is disabled when its corresponding MFB path is set.
  • The editor preview attempts to resolve the path from available mfb/value context.

Frontend behaviour with paths​

  • render.php resolves the same paths from block context (mfb/value) server-side.
  • This keeps frontend output consistent even when editor preview cannot fully resolve nested data.
Path format

Use / as the delimiter and provide the path relative to the current MFB context.

Example valid values:

  • phone
  • group/phone
  • contact/primary/phone

Compatibility​

  • Works with any plugin that uses register_block_bindings_source() to register a binding source.
  • Works with ACF fields when used via a Custom Meta Block that passes the field value as a binding.
  • The __experimentalConnections support flag is declared in block.json for maximum editor compatibility.

Technical notes (for developers)​

  • Block name: yoko-core/phone-number
  • Rendered server-side via render.php.
  • Shortcode support:
    • Phone Number and Label are processed with do_shortcode() before rendering.
  • Block Bindings support:
    • phone and label attributes support WordPress Block Bindings (WP 6.5+).
    • Binding values are resolved automatically by WordPress before render.php is called.
    • __experimentalConnections is declared in block.json for editor support.
  • MFB path workaround:
    • Optional attributes: mfbPhonePath, mfbLabelPath.
    • The block declares usesContext: ["mfb/value"] in block.json.
    • Server-side path resolution supports scalar values and common MFB node shapes (value, value_formatted, field.value).
  • URL forcing:
    • In Button mode, the block rewrites the first .wp-block-button__link href to the computed tel: link.