---
layout      : 'default'
css         : ''

element     : 'dimmer'
elementType : 'module'

title       : 'Dimmer'
description : "Dimmers hide distractions to focus user's attention on particular content"
type        : 'UI Module'

themes      : ['Default']
---
<link rel="stylesheet/less" type="text/css" href="/build/less/definitions/modules/dimmer.less" />
<script src="/javascript/dimmer.js"></script>

<div class="ui page dimmer">
  <div class="content">
    <div class="center">
      <h2 class="ui inverted icon header">
        <i class="icon circular inverted emphasized green mail"></i>
        You're all signed up for the weekly dog tips newsletter!
        <div class="sub header">Your first edition will be sent on January 22</div>
      </h2>
    </div>
  </div>
</div>

<%- @partial('header', { tabs: 'module' }) %>

<div class="main container">

  <div class="active ui tab" data-tab="definition">

    <div class="peek">
      <div class="ui vertical pointing secondary menu">
        <a class="item">Types</a>
        <a class="item">States</a>
        <a class="item">Variations</a>
      </div>
    </div>

    <h2 class="ui dividing header">Types</h2>

    <div class="example">
      <h4 class="ui header">Content Dimmer</h4>
      <p>A dimmer can display content</p>
      <div class="ui ignored info message">Content must be included inside <code>.content .center</code> to display centered correctly in the modal.</div>
      <div class="ui segment">
        <h4 class="ui dividing header">
          <i class="photo icon"></i>Dog Photos
        </h4>
        <img src="/images/demo/item1.jpg">
        <img src="/images/demo/item2.jpg">
        <div class="ui dimmer">
          <div class="content">
            <div class="center">
              <h2 class="ui inverted icon header">
                <i class="icon circular inverted emphasized red heart"></i>
                Your poodle photo uploaded successfully!
              </h2>
            </div>
          </div>
        </div>
      </div>
      <div class="ui icon buttons">
        <div class="ui show button"><i class="plus icon"></i></div>
        <div class="ui hide button"><i class="minus icon"></i></div>
      </div>
      <div class="existing code">
        <div class="ui dimmer">
          <div class="content">
            <div class="center">
              <h2 class="ui inverted icon header">
                <i class="icon circular inverted emphasized red heart"></i>
                Your poodle photo uploaded successfully!
              </h2>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="example">
      <h4 class="ui header">Page Dimmer</h4>
      <p>A dimmer can be formatted to be fixed to the page</p>
      <div class="existing code">
      <div class="ui page dimmer">
        <div class="content">
          <div class="center">Hello</div>
        </div>
      </div>
      </div>
      <div class="ui page button"><i class="plus icon"></i> Show</div>
    </div>


    <h2 class="ui dividing header">States</h2>

    <div class="example">
      <h4 class="ui header">Active</h4>
      <p>An active dimmer will dim its parent container</p>
      <div class="ui segment">
        <div class="ui active dimmer"></div>
      </div>
    </div>

    <div class="example">
      <h4 class="ui header">Disabled</h4>
      <p>A disabled dimmer cannot be activated</p>
      <div class="ui segment">
        <div class="ui disabled dimmer"></div>
      </div>
    </div>

    <h2 class="ui dividing header">Variations</h2>

    <h3>Dimmer</h3>
    <div class="example">
      <h4 class="ui header">Simple Dimmer</h4>
      <p>A dimmer can be controlled without javascript</p>
      <div class="ignored ui info message">Having any parent element receive the class <code>ui dimmable dimmed</code> will trigger the dimmer to display.</div>
      <div class="ui dimmable dimmed segment">
        <div class="ui simple dimmer"></div>
        <p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec odio. Quisque volutpat mattis eros. Nullam malesuada erat ut turpis. Suspendisse urna nibh, viverra non, semper suscipit, posuere a, pede.</p>
        <p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec odio. Quisque volutpat mattis eros. Nullam malesuada erat ut turpis. Suspendisse urna nibh, viverra non, semper suscipit, posuere a, pede.</p>
      </div>
    </div>

    <div class="example">
      <h4 class="ui header">Inverted Dimmer</h4>
      <p>A dimmer can be formatted to have its colors inverted</p>
      <div class="ui segment">
        <div class="ui inverted dimmer"></div>
        <p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec odio. Quisque volutpat mattis eros. Nullam malesuada erat ut turpis. Suspendisse urna nibh, viverra non, semper suscipit, posuere a, pede.</p>
        <p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec odio. Quisque volutpat mattis eros. Nullam malesuada erat ut turpis. Suspendisse urna nibh, viverra non, semper suscipit, posuere a, pede.</p>
      </div>
      <div class="ignore ui icon buttons">
        <div class="ui show button"><i class="plus icon"></i></div>
        <div class="ui hide button"><i class="minus icon"></i></div>
      </div>
    </div>
  </div>
  <div class="ui tab" data-tab="examples">

    <div class="event example">
      <h4 class="ui header">Dimmer Events</h4>
      <p>A dimmer can trigger a visibility change on an event</p>
      <div class="evaluated code">
      $('.event.example .image')
        .dimmer({
          on: 'hover'
        })
      ;
      </div>
      <div class="ui medium image">
        <div class="ui dimmer">
          <div class="content">
            <div class="center">
              <h2 class="ui inverted header">Puppy</h2>
              <div class="ui green button">Vote</div>
              <a class="ui button">View</a>
            </div>
          </div>
        </div>
        <img src="/images/demo/highres.jpg">
      </div>
      <div class="ui circular image">
        <div class="ui dimmer">
          <div class="content">
            <div class="center">
              <div class="ui mini green button">Vote</div>
              <a class="ui mini button">View</a>
            </div>
          </div>
        </div>
        <img src="/images/demo/photo2.jpg">
      </div>
    </div>

    <div class="example">
      <h4 class="ui header">Loaders inside Dimmers</h4>
      <p>Any loader inside a dimmer will automatically use an appropriate color to match</p>
      <div class="ui segment">
        <div class="ui inverted dimmer">
          <div class="ui text loader">Loading</div>
        </div>
        <p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec odio. Quisque volutpat mattis eros. Nullam malesuada erat ut turpis. Suspendisse urna nibh, viverra non, semper suscipit, posuere a, pede.</p>
        <p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec odio. Quisque volutpat mattis eros. Nullam malesuada erat ut turpis. Suspendisse urna nibh, viverra non, semper suscipit, posuere a, pede.</p>
      </div>
      <div class="ignore ui icon buttons">
        <div class="ui show button"><i class="plus icon"></i></div>
        <div class="ui hide button"><i class="minus icon"></i></div>
      </div>
    </div>

  </div>

  <div class="ui tab" data-tab="usage">

    <h2 class="ui dividing header">Usage</h2>

    <h3 class="ui header">Display</h3>
    <p>You can display a dimmer by either invoking .dimmer('show') on a section or a dimmer itself. If you choose to dim a dimmable section, a dimmer will automatically be created.</p>
    <div class="ignore code">
    // these two are the same
    $('.ui.dimmable)
      .dimmer('show')
    ;
    $('.ui.dimmable .dimmer')
      .dimmer('show')
    ;
    </div>

    <h3 class="ui header">Creating Dimmers</h3>
    <p>If a dimmer does not exist inside the element it will be created on first use.</p>
    <div class="code" data-demo="true">
      $('h3')
        .dimmer('toggle')
      ;
    </div>
    <h3 class="ui header">Showing a specific dimmer</h3>
    <p>If a dimmer is already inside an element, you can call behavior on the dimmable section or the dimmer itself.</p>
    <div class="code" data-demo="true">
      // If a dimmer exists on a page, you can make it appear by calling it directly
      $('.page.dimmer:first')
        .dimmer('toggle')
      ;
    </div>

    <h2 class="ui dividing header">Behavior</h2>

    <p>All the following <a href="/module.html#/behavior">behaviors</a> can be called using the syntax:</p>
    <div class="code">
    $('.your.element')
      .dimmer('behavior name', argumentOne, argumentTwo)
    ;
    </div>

    <table class="ui definition celled sortable table segment">
      <thead>
        <th>Behavior</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>add content (element)</td>
          <td>Detaches a given element from DOM and reattaches element inside dimmer</td>
        </tr>
        <tr>
          <td>show</td>
          <td>Shows dimmer</td>
        </tr>
        <tr>
          <td>hide</td>
          <td>Hides dimmer</td>
        </tr>
        <tr>
          <td>toggle</td>
          <td>Toggles current dimmer visibility</td>
        </tr>
        <tr>
          <td>get duration</td>
          <td>Returns current duration for show or hide event depending on current visibility</td>
        </tr>
        <tr>
          <td>get dimmer</td>
          <td>Returns DOM element for dimmer</td>
        </tr>
        <tr>
          <td>has dimmer</td>
          <td>Returns whether current dimmable has a dimmer</td>
        </tr>
        <tr>
          <td>is dimmer</td>
          <td>Whether current element is a dimmer</td>
        </tr>
        <tr>
          <td>is dimmable</td>
          <td>Whether current element is a dimmable section</td>
        </tr>
        <tr>
          <td>is active</td>
          <td>Whether section's dimmer is active</td>
        </tr>
        <tr>
          <td>is animating</td>
          <td>Whether dimmer is animating</td>
        </tr>
        <tr>
          <td>is page</td>
          <td>Whether dimmable section is <code>body</code></td>
        </tr>
        <tr>
          <td>is enabled</td>
          <td>Whether dimmer is not disabled</td>
        </tr>
        <tr>
          <td>is disabled</td>
          <td>Whether dimmer is disabled</td>
        </tr>
        <tr>
          <td>is page dimmer</td>
          <td>Whether dimmer is a page dimmer</td>
        </tr>
        <tr>
          <td>set active</td>
          <td>Sets page dimmer to active</td>
        </tr>
        <tr>
          <td>set dimmable</td>
          <td>Sets an element as a dimmable section</td>
        </tr>
        <tr>
          <td>set dimmed</td>
          <td>Sets a dimmable section as dimmed</td>
        </tr>
        <tr>
          <td>set page dimmer</td>
          <td>Sets current dimmer as a page dimmer</td>
        </tr>
        <tr>
          <td>set disabled</td>
          <td>Sets a dimmer as disabled</td>
        </tr>
      </tbody>
    </table>

  </div>

  <div class="ui tab" data-tab="settings">

    <h3 class="ui header">
      Dimmer Settings
      <div class="sub header">Dimmer settings modify its behavior</div>
    </h3>
    <table class="ui sortable celled definition table segment">
      <thead>
        <th>Setting</th>
        <th class="four wide">Default</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>closable</td>
          <td class="six wide">true</td>
          <td>Whether clicking on the dimmer should close it automatically</td>
        </tr>
        <tr>
          <td>on</td>
          <td class="six wide">false</td>
          <td>Can be set to <code>hover</code> or <code>click</code> to show/hide dimmer on dimmable event</td>
        </tr>
        <tr>
          <td>duration</td>
          <td>
            <div class="code">
      duration    : {
        show : 500,
        hide : 500
      }
            </div>
          </td>
          <td>Animation duration of dimming. If an integer is used, that value will apply to both show and hide animations.</td>
        </tr>
        <tr>
          <td>transition</td>
          <td>
            Fade
          </td>
          <td>Named transition to use when animating menu in and out. Fade and slide down are available without including <a href="/modules/transition.html">ui transitions</a></td>
        </tr>
      </tbody>
      </tbody>
    </table>

    <h3 class="ui header">
      Callbacks
      <div class="sub header">Callbacks specify a function to occur after a specific behavior.</div>
    </h3>

    <table class="ui sortable celled definition table segment">
      <thead>
        <th class="four wide">Setting</th>
        <th>Context</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>onShow</td>
          <td>dimmable</td>
          <td>Callback on element show</td>
        </tr>
        <tr>
          <td>onHide</td>
          <td>dimmable</td>
          <td>Callback on element hide</td>
        </tr>
        <tr>
          <td>onChange</td>
          <td>dimmable</td>
          <td>Callback on element show or hide</td>
        </tr>
      </tbody>
    </table>

    <h3 class="ui header">
      Templates
      <div class="sub header">Templates are used to generate DOM elements</div>
    </h3>

    <table class="ui sortable celled definition table segment">
      <thead>
        <th class="three wide">Generates</th>
        <th>Default</th>
      </thead>
      <tbody>
        <tr>
          <td>dimmer</td>
          <td>
            <div class="code" data-type="javascript">
            function() {
             return $('<div />').attr('class', 'ui dimmer');
            }
            </div>
          </td>
        </tr>
      </tbody>
    </table>

    <h3 class="ui header">
      DOM Settings
      <div class="sub header">DOM settings specify how this module should interface with the DOM</div>
    </h3>
    <table class="ui sortable celled definition table segment">
      <thead>
        <th>Setting</th>
        <th class="six wide">Default</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>namespace</td>
          <td>dimmer</td>
          <td>Event namespace. Makes sure module teardown does not effect other events attached to an element.</td>
        </tr>
        <tr>
          <td>selector</td>
          <td>
            <div class="code" data-type="css">
            selector: {
              dimmable : '.ui.dimmable',
              dimmer   : '.ui.dimmer',
              content  : '.ui.dimmer > .content, .ui.dimmer > .content > .center'
            }
            </div>
          </td>
          <td>Object containing selectors used by module.</td>
        </tr>
        <tr>
          <td>className</td>
          <td>
            <div class="code">
            className : {
              active     : 'active',
              dimmable   : 'ui dimmable',
              dimmed     : 'dimmed',
              disabled   : 'disabled',
              pageDimmer : 'page',
              hide       : 'hide',
              show       : 'show',
              transition : 'transition'
            }
            </div>
          </td>
          <td>Class names used to attach style to state</td>
        </tr>
      </tbody>
    </table>

    <h3 class="ui header">
      Debug Settings
      <div class="sub header">Debug settings controls debug output to the console</div>
    </h3>

    <table class="ui sortable celled definition table segment">
      <thead>
        <th>Setting</th>
        <th class="four wide">Default</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>name</td>
          <td>Dimmer</td>
          <td>Name used in debug logs</td>
        </tr>
        <tr>
          <td>debug</td>
          <td>True</td>
          <td>Provides standard debug output to console</td>
        </tr>
        <tr>
          <td>performance</td>
          <td>True</td>
          <td>Provides standard debug output to console</td>
        </tr>
        <tr>
          <td>verbose</td>
          <td>True</td>
          <td>Provides ancillary debug output to console</td>
        </tr>
        <tr>
          <td>errors</td>
          <td colspan="2">
            <div class="code">
            error   : {
              method   : 'The method you called is not defined.'
            }
            </div>
          </td>
        </tr>
      </tbody>
    </table>

  </div>

</div>