Snippets: Howto Grey-Out The Screen

This snippet grays out the screen and allows you to create a modal environment. A gray out is useful for creating a DHTML dialog box, or showing off a picture or video. While a gray-out is active, most interactive elements on the page (links, etc) are inactive.

This is a new feature of this blog. Snippets are short blocks of useful toolbox code which are not necessarily worth a full-in depth article. If you like, just clip them to your toolbox (all the <pre>/gray code blocks on this site contain code which has been placed into the public domain.

This snippet grays out the screen and allows you to create a modal environment. A gray out is useful for creating a DHTML dialog box, or showing off a picture or video. While a gray-out is active, most interactive elements on the page (links, etc) are inactive.

A gray-out is a dynamically created layer which is stretched to fill the entire document. It covers the existing document from top to bottom. The gray-out has a relatively high z-index which means it's placed on top of the rest of the page. Items which have a higher z-index than the gray-out layer will appear on top of the gray-out and the user can interact with those items.

By default the gray-out has a z-index of 50, after graying out the screen you should assign a zindex higher than 50 to the content you want the user to interact with.

Example. This snippet has been tested in Firefox 2, Opera 9, and Internet Explorer 7.

function grayOut(vis, options) {
  // Pass true to gray out screen, false to ungray
  // options are optional.  This is a JSON object with the following (optional) properties
  // opacity:0-100         // Lower number = less grayout higher = more of a blackout 
  // zindex: #             // HTML elements with a higher zindex appear on top of the gray out
  // bgcolor: (#xxxxxx)    // Standard RGB Hex color code
  // grayOut(true, {'zindex':'50', 'bgcolor':'#0000FF', 'opacity':'70'});
  // Because options is JSON opacity/zindex/bgcolor are all optional and can appear
  // in any order.  Pass only the properties you need to set.
  var options = options || {}; 
  var zindex = options.zindex || 50;
  var opacity = options.opacity || 70;
  var opaque = (opacity / 100);
  var bgcolor = options.bgcolor || '#000000';
  var dark=document.getElementById('darkenScreenObject');
  if (!dark) {
    // The dark layer doesn't exist, it's never been created.  So we'll
    // create it here and apply some basic styles.
    // If you are getting errors in IE see: http://support.microsoft.com/default.aspx/kb/927917
    var tbody = document.getElementsByTagName("body")[0];
    var tnode = document.createElement('div');           // Create the layer.
        tnode.style.position='absolute';                 // Position absolutely
        tnode.style.top='0px';                           // In the top
        tnode.style.left='0px';                          // Left corner of the page
        tnode.style.overflow='hidden';                   // Try to avoid making scroll bars            
        tnode.style.display='none';                      // Start out Hidden
        tnode.id='darkenScreenObject';                   // Name it so we can find it later
    tbody.appendChild(tnode);                            // Add it to the web page
    dark=document.getElementById('darkenScreenObject');  // Get the object.
  }
  if (vis) {
    // Calculate the page width and height 
    if( document.body && ( document.body.scrollWidth || document.body.scrollHeight ) ) {
        var pageWidth = document.body.scrollWidth+'px';
        var pageHeight = document.body.scrollHeight+'px';
    } else if( document.body.offsetWidth ) {
      var pageWidth = document.body.offsetWidth+'px';
      var pageHeight = document.body.offsetHeight+'px';
    } else {
       var pageWidth='100%';
       var pageHeight='100%';
    }   
    //set the shader to cover the entire page and make it visible.
    dark.style.opacity=opaque;                      
    dark.style.MozOpacity=opaque;                   
    dark.style.filter='alpha(opacity='+opacity+')'; 
    dark.style.zIndex=zindex;        
    dark.style.backgroundColor=bgcolor;  
    dark.style.width= pageWidth;
    dark.style.height= pageHeight;
    dark.style.display='block';				 
  } else {
     dark.style.display='none';
  }
}

Activate/Deactivate with a function call to grayOut(vis, options). vis is a true/false variable. If you pass true, the screen will be grayed out. If you pass false, the gray-out will be removed.

options is an optional JSON object this allows you to send only the properties you want modified. You don't have to pass options if you don't want. grayOut(true) and grayOut(false) will work quite nicely. The three properties looked for in options are zindex, opacity, and bgcolor.

By default the gray-out creates a layer with a z-index of 50 and you will need to create or raise elements's z-indexes to be higher than 50 to appear on top of the gray-out. If you need to, however, you can set an option of {'zindex':'50'} where 50 is is changed to the z-index you wish to use.

The default opacity of the grayout is 70, you can change this to a number between 0 and 100 by setting the opacity property: {'opacity':'25'} Opacity 25

The default background color is black (which creates a gray layer), if you'd like to use another color, set the bgcolor property: {'bgcolor':'#0000FF'}. Blue BG Example

The options are comma deliminated so to set an opacity and background color: {'opacity':'25', 'bgcolor':'#0000FF' }. Blue BG/Opacity 25 Example

To set all three: {'opacity':'70', 'bgcolor':'#0000FF', 'zindex':'25' }. Order doesn't matter, mix and match however you wish.