Part of WordPress Integration — 4 of 4.

Best Practices & Troubleshooting

✅ Best Practices

• One script tag, one location only. Place the <script> tag in footer.php (or the WPCode snippet) and nowhere else. If the same script also appears in a Custom HTML block, two widget instances load simultaneously — causing duplicate launchers and duplicate text boxes.
• No script tag inside Custom HTML blocks. Once the site-wide script is set up, Custom HTML blocks should contain only trigger elements (the textbox div, pill links). Never paste the script tag there.
• Place the script before wp_footer(). WordPress relies on the wp_footer() hook firing last. Insert ZipTier's script just above it — not after </body>.
• Classic theme required. If your theme has no footer.php in Theme File Editor, switch to a classic theme (Astra recommended) before following this guide.
• Test in an incognito window. Your browser stores a prior widget session cookie. Incognito mode resets it and shows what a first-time visitor sees.

🔧 Troubleshooting

Two launchers or two text boxes appear on a page

The script tag exists in both footer.php and a Custom HTML block on the same page. Remove the script tag from the Custom HTML block — keep only the trigger elements there.

The textbox or pills don't appear on the page

• Check the browser console for [ZipTier Widget] v1.x script loaded. If it's missing, the script in footer.php is not loading — verify the file was saved.
• Make sure the Custom HTML block contains a div with class="ziptier-widget-trigger" and data-button-style="textbox".
• Confirm the WordPress block editor has not converted the Custom HTML block into a paragraph — switch to Code Editor view to check.

Pill labels are empty

WordPress strips text content from <button> tags in Custom HTML blocks. Switch to <a> tags and put the label text between the opening and closing tags.

Theme File Editor is missing from Appearance menu

Some managed hosts or security plugins disable it. Use the free WPCode plugin as an alternative — see Adding the Script via WPCode.

← Adding Custom Triggers  |  WordPress Integration overview →