Summary: Adds links or buttons for toggling (hiding/showing) div sections and objects
Version: 2017-06-17
Prerequisites: PmWiki 2.2.56 (compatible with PHP 5.5)
Status: stable
Maintainer: HansB
License: GPL2+
Categories: Layout Links PHP55 PHP72
Discussion: Toggle-Talk
Users: +13 (View / Edit)
Download: toggle.phpΔ

Toggle Popup Box

This is an example of what this recipe
can do. This is an absolutely positioned
div element. See the page source for more

This recipe depends on javascript.

Questions answered by this recipe

How can I add toggle switches to show and hide sections of the page?


The script adds markup for links, buttons or images for toggling (hiding/showing) div sections and objects

Download toggle.phpΔ and copy to cookbook folder. Install by adding to config.php:


Toggle button examples: Short syntax:

(:toggle hide box1 button=1:)
>>id=box1 border='1px solid #999' padding=5px bgcolor=#edf<< 
The text in this section can be hidden/shown 

The text in this section can be hidden/shown

Long syntax:

(:toggle id=box2 init=hide button=1:)
>>id=box2 border='1px solid #999' padding=5px bgcolor=#edf<< 
The text in this section can be hidden/shown 

The text in this section can be hidden/shown

Toggle link examples:

(:toggle box3:)
>>id=box3 border='1px solid #999' padding=5px bgcolor=#fed<< 
The text in this section can be hidden/shown 


The text in this section can be hidden/shown

(:toggle hide box4:)
>>id=box4 border='1px solid #999' padding=5px bgcolor=#fed<< 
The text in this section can be hidden/shown 


The text in this section can be hidden/shown

(:toggle box5a box5b:)
>>id=box5a border='1px solid #999' padding=5px bgcolor=#fed<< 
Toggle between two divs. First div.
>>id=box5b border='1px solid #999' padding=5px bgcolor=#edf<< 
Some text in second div.  


Toggle between two divs. First div.

Some text in second div.

Necessary parameter:

id of division or object which the toggle link or button acts on. Alternatively first word is used as id.
Example: togglelink (:toggle abc:) on div >>id=abc<<

Optional parameters:

id of an optional second div or object which the toggle will show when hiding the first div, toggling between the two divs or objects.
hides the division initially (default is show)
text of link/button when div is hidden (default is show)
label of button when div is shown (default is hide)
label of link or button for both toggle states (setting the show to be the same as the hide label)
remember toggle state by setting a cookie
display a button instead of a link
New group=<classname>
on clicking show show div with associated id= (standard behaviour), but hide all other divs with class classname.
New ttshow=<tooltiptext>
text that appears when the user hovers over the "show" link (default is Show)
New tthide=<tooltiptext>
text that appears when the user hovers over the "hide" link (default is Hide)
New nojs=<integer>
set to 1 or 2 will show toggle links/buttons if browser does not support javascript. Set to 2 will hide hidden divs via style in page head and not via javascript, so that for non-js browser initially hidden divs stay hidden.

Shortcut syntax:

You can avoid some of the parameter keywords and use keyless arguments in the markup instead.

  • (:toggle divname:) same as (:toggle id=divname:)
  • (:toggle hide divname:) same as (:toggle init=hide id=divname:)
  • (:toggle hide divname button:) same as (:toggle init=hide id=divname button=1:)
  • (:toggle name1 name2:) same as (:toggle id=name1 id2=name2:)


For custom labels set labels with parameters show= or hide= (or label= for one 'show' and 'hide' label).
Single quotes (apostrophes) in labels should work now.

Images as toggles

You can have images displayed instead of link text. Use the image file name with extension as label text, like show=myshow.gif hide=myhide.gif. Then clicking the image will toggle the div display, and if you use different images for show and hide these images will toggle as well.

Images should be attached to the page (use action=upload to upload file to page or group). Syntax like label=Attach:myimage.ext Δ does not work. If your uploaded image file is attached to a different group, for instance it is uploaded to the 'Site' group, then use syntax like show=Site/myshow.gif. - The toggle markup recognises images with extensions png, gif, jpg, jpeg and ico. If there are problems with uploading such images, make sure you follow all the advice about uploading images and necessary permissions are set.

group=<classname> option

A new option to enable hiding a number of divs with class <classname> while showing the div associated with id.
Note that this works well with default Show and Hide labels used in multiple toggle links, but if your toggle links have individually different labels, Toggle will mess up the display of these when group=<classname> is set. This is a known bug, and I have not found a way how the javascript can get all the correct labels for the associated toggle links when toggling multiple divs.

config.php parameters

Array $ToggleConfig
for setting defaults in config.php. See script for possible options.

Backward compatibility

The script is backwards compatible with the togglelink markup syntax. lshow= works same as show= parameter, lhide= works same as hide= parameter, div= works same as id= parameter, div2= works same as id2= parameter. Buttons are implemented with a button=1 parameter, and work that way like ShowHide Buttons.

This recipe supersedes the ShowHide and ToggleLink scripts.


The script requires a javascript enabled modern browser. It places a javascript function into the html body, which will achieve instant toggle effects without page reloads.

A toggle button can act on any named division of the page, even a sidebar or other structural division outside the normal page content. But in such a case it may not make a too good job, because to hide such a div effectively may need more than applying display:none, for instance resetting of margins.

A toggle button can also act on other objects with an id= set, for instance tables. It is not restricted to divs.

A toggle button or link can toggle two divisions or objects, hiding one and showing the other, alternating. Name the first division or object id with id=... and the second with id2=...

Two toggle buttons or two toggle links can act together as a pair on one div. For instance put one on top of the div, and the other inside at the bottom, to conveniently close it. But note that the label or link text of the second one will be displayed on the first one when clicked, so use the same labels for both. And if the div shall be initially hidden, place init=hide into the first markup and not the second.

Ensure that the skin/template you're using has a <!--HTMLFooter--> tag towards the bottom. This is needed to load the JavaScript (old version skin hasn't this tag).

Tip: If you want any initially hidden div or object to be hidden while the page is loading (since some pages load slowly and javascript does not hide the divs instantaneously):
define 'hide' as a general class in pub/local.css with

.hide {display:none;}

and add the class 'hide' to the divs or objects, for instance like this:

(:toggle abc init=hide:)
>>id=abc hide<<
hidden content...
Tip: To show a set of divs with a single click, without them all having the same id (so they can also be individually toggled) you can use the Cookbook:HttpVariables recipe. For example, you can set init=hide in config, so the toggles default to hidden. Then base the initial value of each toggle that you want to participate in "Show all" on a URL request variable, e.g (:toggle {$?showstatus} myhiddendiv1:). Then provide on the page a link such as "[[{*$FullName}?showstatus=show|Show all]]". The page will normally hide the participating divs, but if the user clicks the link the page will reload with the selected divs all shown.

Release Notes

  • 2017-06-17: updated markup definition to be PHP 7.2 compatible.
  • 2014-02-21: updated markup definition to be PHP 5.5 compatible.
  • 2011-04-06: changed js code to always set display attribute.
  • 2011-04-04: fixed bug inhibiting initial hiding of divs if toggle was in SideBar or other subpage.
  • 2011-04-03: added nojs= option for controlling js/non-js behaviour. Changed non-js default behaviour to show only one div when toggling between two.
  • 2011-03-30: fixed Toggle to make it non-javascript friendly. Added tooltips to links. Added grouped toggling.
  • 2009-07-23: fixed bug preventing initial state in sidebar. Fixed bug in cookie name.
  • 2009-03-09: added image option
  • 2009-03-06: initial release, as an upgrade to ShowHide and ToggleLink scripts, combining both, and expanding the syntax.
    Changes from Showhide/ToggleLink:
    Disbanded showhide and togglelink markup in favour of new (:toggle ... :) markup. Fixed single quotes in labels. Added button=1 parameter. Changed parameter names, but the old ones should still work. Added shortcut parameter syntax. Tidied up javascript.

See Also

  • ShowHide - original recipe, now superseded.
  • AddToggle - A GUIEdit button to convert selected text to a toggle link
  • UnToggle - A show/hide switch where the contents is visible even for browsers with JavaScript disabled.
  • Request - lets the user change what is shown without javascript, by calling the page again with a URL request


See discussion at Toggle-Talk

User notes +13: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.