I am a

UX Guidelines

A callout is a panel of content that "pops up" when the user initializes its appearance from a trigger element, presenting more information about the trigger element. This allows the user to get more information about an element without actually leaving the page and without interrupting the user's current task.


Types of Callouts

The types of callouts and their usage can be categorized as follows:

Tooltip callout
A text only callout which provides additional information about a span of text or a link.
Menu callout
A drop-down "menu" of links which can be triggered by any element, such as a button, link, or icon.
Form input callout
A callout that provides additional information about a form field when the user focuses the mouse cursor on that field.
Cursor callout
A callout which follows the mouse cursor. This will typically be triggered on hover of a media element, such as an image.
Other Callout
A callout that does not fall into any of the above categories; can contain any type of content (i.e., text, images, calls to action, etc.) and is triggered by any element, such as a button, link, or icon.

Callout styles

There are three callout styles:

Light background (default)
A white background with a soft drop shadow. This is the default style and should be used for most callouts.
Dark background
A dark, shaded leaf green background with a thin, white border. This is to be used on pages with a light background.
Alt Style for Interactive Image Viewer (IIV) pages
This style has been specifically defined for IIV pages and should not be used anywhere else.

How to use

  • Only use a callout if it is necessary to provide more information to the user without leaving the current page.
  • Do not overload callouts with too much information. If there’s too much information, the user should just be taken to another page.
  • Ensure that callouts happen within the viewport so as not to cause unnecessary scrolling or a callout that is hidden from view.
  • Limit the functionality within a callout to clickable links/buttons. If more functionality is needed, consider using a modal.

Examples of when to use

  • On a user’s name to get more information about the user.
  • On a search result link to get more information about the record.
  • To provide more information about a family tree node.

Coding Guidelines

Prerequisites


Instructions

  1. Create the callout and its trigger in either the HTML or JavaScript:

    • In HTML: callout.js automatically instantiates any element with a [data-callout] attribute on page load, so it is very easy to add a little markup to create a callout. For example:

      <button data-callout="<p>callout content goes here</p>" type="button">HTML</button>
      <!-- The [data-callout] attribute does accept HTML markup, but make sure to test that it displays properly -->
      Syntax for creating a static callout.

      OR

    • In JavaScript: You can do the same thing by calling callout.js to instantiate a callout on dynamic content or any other element. This allows binding on onOpen and onClose callbacks as needed. For example:

      $('#callout-trigger-example2').callout({
      	'content': '<p>Callout content goes here</p>' /* Accepts a string, HTML or a selector (or a function that returns one of those) */
      });
      Syntax for creating a callout dynamically.
    • If the content of a callout is a part of your semantic outline, specify the selector of the callout content in the content callout setting:

      Menu
      <button class="ancBtn" id="your-callout-id" type="button">Content in DOM</button>
      <div id="your-callout-content" class="calloutDomContent">
      	<h5 class="calloutMenuTitle">Menu</h5>
      	<ul class="calloutMenu">
      		<li>
      			<button type="button" class="link calloutMenuUnchecked iconAfter iconAfterCheck icon iconGallery">Title</button>
      		</li>
      	</ul>
      </div>
      $('#yourCalloutID').callout({
      'content': '#yourCalloutContent'
      });
      Syntax for creating a callout when content is in the DOM.

    Note: The element that triggers the callout should be a <button/> in most cases.

  2. Account for special use cases.

    • Drop-down menus: Pass calloutMenu through the [data-callout-classes] attribute or in the 'classes' setting to create a callout menu (drop-down menu). See the example.

    • Tooltips: Add the class .calloutTooltip to create a callout tooltip. See the example.

    • Form inputs: Add a callout to a form input to create a form input callout. See the example.

  3. Tweak the options by doing one of the following:

    • Add a class modifier to the trigger element (see available class modifiers):

      <button class="ancBtn orange calloutStyleDark" data-callout="

      Example callout with calloutMenu class modifier.

      " type="button">Click Here</button>

      OR

    • Pass settings in the JavaScript call (see available settings):

      $('#callout-trigger-example3').callout({
      	'content': '

      Callout content goes here

      ', 'position': 'right', 'type': 'hover' });
  4. Other things you can do with callouts:

    • Use the available public methods to perform specific actions with a callout.

    • Add your own styles to a callout's content by placing a class name in the [data-callout-classes] attribute of the trigger element (no dot, separate multiple classes with a space).

      <button data-callout-classes="calloutMenu customClass1 customClass2" data-callout="Insert callout content here" type-"button"><!-- Trigger text --></button>

Basic Callout Example

See more examples

With HTML:

<button data-callout="<p>I am the content passed through the <code>[data-callout]</code> attribute.</p><img src='http://mediasvc.ancestrydev.com/image/3a9f5c7b-db0c-4a0e-9331-be4df1aa0210.jpg?Client=Trees&NamespaceID=1093&MaxSide=256' width='256' alt='This is an image inside a basic callout.' style='width:100%'/>" type="button" class="link">I will show a normal callout.</button>

OR

With JavaScript:

$('#callout-trigger-example4').callout({
	'content': '<p>I am the content passed through the <code>\'content\'</code> setting.</p><img src="http://mediasvc.ancestrydev.com/image/3a9f5c7b-db0c-4a0e-9331-be4df1aa0210.jpg?Client=Trees&NamespaceID=1093&MaxSide=256" width="256" alt="This is an image inside a basic callout."/>',
});
The same basic callout with JavaScript

Settings

While the JS values below are simply passed in as jQuery plugin options, the same result can be achieved on auto-instantiated callouts by adding the equivalent class modifiers to the class attribute of the trigger element.

This table lists each available setting for the callout widget.
Setting JS values Class modifiers Details
Setting JS values Class modifiers Details
'align' 'center' (default)
'left'
'right'
'top'
calloutAlignLeft
calloutAlignRight
calloutAlignTop
The values 'left' and 'right' do not apply to { position:'left' } or { position:'right' }.
'classes' Add classes here to be applied to the calloutContent wrapper (for example, calloutMenu). You can also use the classes JS value to specify classes for custom styling/interaction.
'content' Insert a string, HTML markup, or selector here, and it will be added as the callout content.

'hideDelay' 100 (default)
other time in ms (200, 300, etc.)
This applies to callouts of type hover.
'hidePointer' false (default)
true
calloutHidePointer Set to true to hide the pointer.
'keepContentInPlace' true (default)
false
Setting true will keep the content in the DOM; false removes it.
'onOpen' false (default)
function ($trigger) { }
Runs a callback before the callout opens.
'onAfterOpen' false (default)
function ($trigger) { }
Runs a callback after the callout opens.
'onClose' false (default)
function ($trigger) { }
Runs a callback before the callout closes.
'position' 'bottom' (default)
'left'
'right'
'top'
calloutPositionTop
calloutPositionRight
calloutPositionLeft
This specifies the position of the callout, relative to the trigger.
'showDelay' 100 (default)
other time in ms (200, 300, etc.)
This specifies the show delay time in ms for callouts of type hover.
'style' 'light' (default)
'dark'
'alt'
calloutStyleAlt
calloutStyleDark
  • Alt - this is only for IIV pages.
  • Dark - gives the callout a dark background with light text.
'type' 'click' (default)
'hover'
'cursor'
'custom'
calloutTypeHover
calloutTypeCursor
calloutTypeCustom
  • Click - the callout will open and close on click.
  • Hover - the callout will open on mouseenter, and close on mouseleave.
  • Cursor - the callout will follow the mouse cursor.
  • Custom - this is not a JS setting, but denotes that you can create a custom event to bind to the callout.

Other class modifiers

calloutTooltip
Add to the trigger to turn it into a tooltip.
calloutTriggerNoArrow
Add to the trigger to hides the drop down arrow on the trigger.
calloutScrollPane
Add this class the callout's trigger's wrapper if the wrapper will be scrollable - like in IIV

Available Methods

  • Open a callout:

    $('#triggerElement').callout('open');
  • Close a callout:

    $('#triggerElement').callout('close');
  • Update a callout's content:

    $.callout.content($('#trigger'), content);
  • Destroy a callout:

    $('#triggerElement').callout('destroy');

Accessibility Considerations

  • An input should not have a callout with focusable items since there is no good way to use a keyboard to get to that part of the page.
  • Callout menus should be as simple as possible. They should not be bloated with unnecessary interactivity or visual effects.