Target.js by gocomet

Getting Started

Target.js works by doing two things:

Adding functionality to elements with the right data-attributes
Add/removing a "target-active" class -- you control the styles

How to use:

Include necessary JavaScript
initialize and configure target.js
add data-attributes to your HTML tags
apply styles to your elements and the "target-active" class

Installation

Step 1. Include the minified or unminified JS file

Grab one of the JS files under dist/. Include them on your page:

<script src="my-js-folder/target.js"></script>

or:

<script src="my-js-folder/target.min.js"></script>

Step 2. Initialize Target.js

<script>
    target.init();
</script>

Step 3. Add data-attributes on your elements

<button data-target-toggle=".minicart">
    Cart
</button>

<div class="minicart">
  This will get toggled!
</div>

Step 4. Add styles to show/hide your elements

.minicart {
  visibility: hidden;
}

.minicart.target-active {
  visibility: visible;
}

Configuration

Target.js' init method accepts a configuration object. Pass your options into target when you initialize it:

target.init(options);

Options

Option	Data Type	Default Value
`activeClass`	`String`	`"target-active"`
	The class name you want Target.js to apply to any "shown" element. Target.js will remove this class when "hiding" an element. (This is how Target.js "shows" and "hides" elements.)
`attributes`	`Object`	See options below
	An object containing key-value pairs of the data-attributes you wish to use to assign Target.js components and declarations.
`attributes.Toggle`	`String` (valid data-attribute)	`"data-target-toggle"`
	The data-attribute you want to use to instantiate Toggle components
`attributes.Show`	`String` (valid data-attribute)	`"data-target-show"`
	The data-attribute you want to use to instantiate Show components
`attributes.Hide`	`String` (valid data-attribute)	`"data-target-hide"`
	The data-attribute you want to use to instantiate Hide components
`attributes.Clickoff`	`String` (valid data-attribute)	`"data-target-clickoff"`
	The data-attribute you want to use to instantiate Clickoff components
`attributes.Increment`	`String` (valid data-attribute)	`"data-target-increment"`
	The data-attribute you want to use to instantiate Increment components
`attributes.Decrement`	`String` (valid data-attribute)	`"data-target-decrement"`
	The data-attribute you want to use to instantiate Decrement components
`attributes.Scrollbox`	`String` (valid data-attribute)	`"data-target-scrollbox"`
	The data-attribute you want to use to instantiate Scrollbox components
`attributes.Grid`	`String` (valid data-attribute)	`"data-target-grid"`
	The data-attribute you want to use to instantiate Grid components
`attributes.Src`	`String` (valid data-attribute)	`"data-target-src"`
	The data-attribute you want to use to instantiate Src components
`attributes.Scroll`	`String` (valid data-attribute)	`"data-target-scroll"`
	The data-attribute you want to use to instantiate Scroll components
`attributes.Filetext`	`String` (valid data-attribute)	`"data-target-filetext"`
	The data-attribute you want to use to instantiate Filetext components
`attributes.Height`	`String` (valid data-attribute)	`"data-target-height"`
	The data-attribute you want to use to instantiate Height components
`attributes.Accordion`	`String` (valid data-attribute)	`"data-target-accordion"`
	The data-attribute you want to use to instantiate Accordion components
`attributes.disable`	`String` (valid data-attribute)	`"data-target-disable"`
	The data-attribute you want to use to disable a component
`attributes.max`	`String` (valid data-attribute)	`"data-target-max"`
	The data-attribute you want to use to declar the max value of an incrementer.
`attributes.min`	`String` (valid data-attribute)	`"data-target-min"`
	The data-attribute you want to use to declar the min value of an decrementer.
`breakpoints`	`Object`	See below
	An object containing key-value pairs defining layouts and their breakpoints. Layouts are designed mobile-first; the mobile layout is not defined — it begins at `0`
`breakpoints.tablet`	`Integer` (in pixels)	`768`
	The minimum screen size (in pixels) at which tablet layout begins.
`breakpoints.desktop`	`Integer` (in pixels)	`1025`
	The minimum screen size (in pixels) at which the desktop layout begins.
`breakpoints.large`	`Integer` (in pixels)	`1440`
	The minimum screen size (in pixels) at which the "large" layout begins.
`debounceDelay`	`Integer` (in milliseconds)	`100`
	Set the debounce delay on the window.resize event handler

Example (with defaults)

<script>
    target.init({
        activeClass: 'target-active',
        attributes: {
            Toggle: 'data-target-toggle',
            Show: 'data-target-show',
            Hide: 'data-target-hide',
            Clickoff: 'data-target-clickoff',
            Increment: 'data-target-increment',
            Decrement: 'data-target-decrement',
            Scrollbox: 'data-target-scrollbox',
            Grid: 'data-target-grid',
            Src: 'data-target-src',
            Scroll: 'data-target-scroll',
            Filetext: 'data-target-filetext',
            Height: 'data-target-height',
            Accordion: 'data-target-accordion',
            disable: 'data-target-disable',
            max: 'data-target-max',
            min: 'data-target-min',
        },
        breakpoints: {
            tablet: 768,
            desktop: 1025,
            large: 1440
        },
        debounceDelay: 100
    });
</script>

modify just what you want:

<script>
    target.init({
        breakpoints: {
            tablet: 640
        }
    });
</script>

or use the default configuration:

<script>
    target.init();
</script>

Components

Show

When clicked, shows the targeted element/elements

Property	Value
Applicable Elements:	any
Applicable Targets:	any
Default Attribute:	`data-target-show`
Attribute Value:	any valid CSS selector

Usage

<button data-target-show="#my-target">
    Show #my-target!
</button>

You can target more than one element:

<div data-target-show="#my-target,.some-more-targets,body">
    Show a bunch of stuff
</div>

Hide

When clicked, hides the targeted element/elements

Property	Value
Applicable Elements:	any
Applicable Targets:	any
Default Attribute:	`data-target-hide`
Attribute Value:	any valid CSS selector

Usage

<button data-target-hide="#my-target">
    Hide #my-target!
</button>

You can target more than one element:

<div data-target-show="#my-target,.some-more-targets,body">
    Hide a bunch of stuff
</div>

Toggle

When clicked, toggles an element

Property	Value
Applicable Elements:	any
Applicable Targets:	any
Default Attribute:	`data-target-toggle`
Attribute Value:	any valid CSS selector

Usage

<button data-target-toggle="#my-target">
    Toggle #my-target!
</button>

You can target more than one element:

<div data-target-show="#my-target,.some-more-targets,body">
    Toggle a bunch of stuff
</div>

Clickoff

When clicked away from, an element will hide itself

Property	Value
Applicable Elements:	any
Applicable Targets:	none
Default Attribute:	`data-target-clickoff`
Attribute Value:	none

Usage

<div data-target-clickoff>
    Click away from this to close!
</div>

Increment/Decrement

Increments or decrements the value of an input. Targeted element must be an <input> element.

Property	Value
Applicable Elements:	any
Applicable Targets:	`<input>`
Default Attribute:	`data-target-increment` or `data-target-decrement`
Attribute Values:	CSS selector targeting one `<input>` element

Usage

<button data-target-decrement="#qty">-</button>
<input id="qty">1</input>
<button data-target-increment="#qty">+</button>

Increments and decrements can have optional min and max values

<button data-target-decrement="#qty" data-target-min="-10">-</button>
<input id="qty">1</input>
<button data-target-increment="#qty" data-target-max="10">+</button>

The default minimum value for decrementers is 0
There is no default maximum value

Scrollbox

Creates a responsive scrollbox. When the content is taller than the threshold, the element gets a scrollbar. When the content isn't, the scrollbar disappears.

Property	Value
Applicable Elements:	any block-display element
Applicable Targets:	none
Default Attribute:	`data-target-scrollbox`
Attribute Value:	height:int

Usage

<div data-target-scrollbox="600">
    <p>If this content goes over 600 pixels tall, the div will get a scrollbar</p>
</div>

If the integer is negative, the threshold will be set relative to the window size:

<div data-target-scrollbox="-300">
    <p>If this content is within 299 pixels of the window height, a scrollbar will appear.</p>
</div>

As with all Target.js elements, Scrollbox updates itself on window.resize.

Grid

Makes elements in a row all the same height. Calculates direct children only. This doesn't replace your CSS grid; rather, it works in conjunction with it.

Property	Value
Applicable Elements:	any
Applicable Targets:	none
Default Attribute:	`data-target-grid`
Attribute Value:	Space-separated list: `mobile-columns:int` `tablet-columns:int` `desktop-columns:int` `large-columns:int`

Usage

<div data-target-grid="2 3 4 4">
    <div>Product thumbnail here</div>
    <div>Product thumbnail here</div>
    <div>Product thumbnail here (these will all have equal height)</div>
    <div>Product thumbnail here</div>
    <div>Product thumbnail here</div>
    <div>Product thumbnail here</div>
    <div>Product thumbnail here (these will all have equal height)</div>
    <div>Product thumbnail here</div>
</div>

Provide a space-separated list of columns per row. In the above example, there are 2 columns per row on mobile, 3 columns per row on tablet, and 4 columns per row on desktop.

An example using Foundation's grid presentational classes:

<div class="row" data-target-grid="2 3 4 4">
    <div class="column small-6 medium-4 large-3">Product thumbnail here</div>
    <div class="column small-6 medium-4 large-3">Product thumbnail here</div>
    <div class="column small-6 medium-4 large-3">Product thumbnail here (these will all have equal height)</div>
    <div class="column small-6 medium-4 large-3">Product thumbnail here</div>
    <div class="column small-6 medium-4 large-3">Product thumbnail here</div>
    <div class="column small-6 medium-4 large-3">Product thumbnail here</div>
    <div class="column small-6 medium-4 large-3">Product thumbnail here (these will all have equal height)</div>
    <div class="column small-6 medium-4 large-3">Product thumbnail here</div>
</div>

Disabling the Grid

You can disable the Grid responsively, like you could any other Target.js element:

<div data-target-grid="1 2 3 4" data-target-disable="mobile">...</div>

Alternatively, you can disable using a shortcut:

<div data-target-grid="disable 2 3 4">...</div>

Src

Responsively loads images. It must be used on an <img> element.

Property	Value
Applicable Elements:	`<img>`
Applicable Targets:	none
Default Attribute:	`data-target-src`
Attribute Value:	Space-separated list: `mobile-img-src:string` `tablet-img-src:string` `desktop-img-src:string` `large-img-src:string`

Usage

<img data-target-src="/some-mobile-img.jpg /my-tablet-image.jpg /a-desktop-image.gif">

The data-target-src accepts a space-separated list of 4 URLs. First, mobile; second, tablet; third, desktop; fourth, large. Because Src is mobile-first, you can omit URLs if you want:

<img data-target-src="/some-mobile-img.jpg /my-tablet-desktop-and-large-image.jpg">

Or, pass a null argument to inherit the smaller image:

<img data-target-src="/some-mobile-and-tablet-img.jpg null /my-desktop-image.jpg">

Or:

<img data-target-src="/used-for-all-layouts.jpg">

The Src component doesn't add its own placeholder image, so be sure to use your own:

<img src="my_blank.gif" data-target-src="/some-mobile-img.jpg /my-tablet-image.jpg /a-desktop-image.gif">

Filetext

Sets an element's innerHTML with an uploaded file's name. Useful for custom-styling file inputs. It must be used on an <input type="file"> element.

Property	Value
Applicable Elements:	`<input type="file">`
Applicable Targets:	any element with an `.innerHTML` property
Default Attribute:	`data-target-filetext`
Attribute Value:	any valid CSS selector

Usage

<input data-target-filetext="#my-filetext-element">

On the file input's change event, the selected file's name will be passed as innerHTML to the element selected in the data-target-filetext attribute. You can use this in conjunction with HTML <label> elements and CSS styles to create completely custom file inputs.

Making a Custom File Input

<label for="my-file-input">
    <input
        type="file"
        id="my-file-input"
        data-target-filetext="#my-file-text"
        style="display: none;">
    <span id="my-file-text">Upload File</span>
</label>

In the above example:

a label tag contains a file input and a span tag
the file input is hidden, so only the span tag inside the label is shown
when the user clicks on the span, they therefore click the label, which invokes the file input functionality
when the user selects a file for upload, the text inside the span is updated automatically, because of the target js data-attribute on the file input

Height

Sets an element's height programmatically. Is updated after resize. Defaults to the window height. Useful for full-screen background-images.

Property	Value
Applicable Elements:	`any`
Applicable Targets:	none
Default Attribute:	`data-target-height`
Attribute Value:	Integer (in pixels) or String ("window")

Usage

<div data-target-height="window">
  Always the window height
</div>

Or:

<div data-target-height="-100">
  Always 100 pixels less than window height
</div>

Or:

<div data-target-height="100">
  Always 100 pixels. Period.
</div>

Scroll

The Scroll componenet gets an active class when it is scrolled into view. You can specify an offset through the component attribute.

Property	Value
Applicable Elements:	any
Applicable Targets:	none
Default Attribute:	`data-target-scroll`
Attribute Value:	`null` or `offset:int`

Usage

<div data-target-scroll>
  This activates when it scrolls into view.
</div>

Or:

<div data-target-scroll="400">
  This activates 400 pixels after it's scrolled into view.
</div>

Accordion

The accordion componenet toggles a set of content.

Property	Value
Applicable Elements:	any
Applicable Targets:	any
Default Attribute:	`data-target-accordion`
Attribute Value:	`toggle-selector:string,content-selector:string`

Usage

<div data-target-accordion=".js-toggle, .js-content">
    <div class="js-toggle">This is a toggle</div>
    <div class="js-content">This is content</div>
    <div class="js-toggle">This is a toggle</div>
    <div class="js-content">This is content</div>
</div>

Layouts

A layout, for our intents and purposes, is a screen size. Target.js uses ~~three~~ four layouts: mobile, tablet, desktop and large. Their default breakpoints are 0px, 768px, 1025px, and 1440px, respectively. You can configure the breakpoints in your configuration

Target.js uses three layouts: mobile, tablet, and desktop. You can disable your Target components on certain layouts, by using Target's "disable" declaration (by default, "data-target-disable".

Layout	Default Breakpoint
Mobile	`0px`
Tablet	`768px`
Desktop	`1025px`
Large	`1440px`

Usage

Using the data-target-disable attribute, pass a space-separated list of layout names:

Attribute	Value(s)
`data-target-disable`	`mobile` `tablet` `desktop` `large`

Example

In the following example, we have a button that toggles the minicart visibility on desktop and tablet devices, but on the mobile layout, it's disabled, so it just links directly to the cart page.

<a href="/cart" data-target-toggle="#minicart" data-target-disable="mobile">
    Cart
</a>

You can disable any Target.js component for any layout or any number of layouts. For example:

<a href="/cart" data-target-toggle="#minicart" data-target-disable="mobile tablet">
    Cart
</a>

Now, the toggle button only toggles on desktop: it links to /cart on mobile and tablet layouts.

Methods

Target.js is designed to be declarative, so that you don't have to write any JavaScript to use it. However, you may want to. Target.js also provides a programmatic API to hook into Target.js functionality. All methods have the exact same effect as their declarative counterparts.

Method	Description	Arguments	Returns
`show`	Shows an element/elements	`<el:DOMElement>` or `<els:NodeList>` or `<cssSelector:String>`	target.api
`hide`	Hides an element/elements	`<el:DOMElement>` or `<els:NodeList>` or `<cssSelector:String>`	target.api
`toggle`	Toggles an element/elements	`<el:DOMElement>` or `<els:NodeList>` or `<cssSelector:String>`	target.api
`on`	Bind a Target event handler to an element	`<eventName:String>`, `<el:DOMElement>` or `<els:NodeList>` or `<cssSelector:String>`, `<callback:Function>`	target.api
`off`	Remove a Target event handler from an element	`<eventName:String>`, `<el:DOMElement>` or `<els:NodeList>` or `<cssSelector:String>`, `<callback:Function>`	target.api
`on`	Bind a Target event handler to the window resizer service	`<eventName:String>`, `<callback:Function>`	target.api
`off`	Remove a Target event handler from the window resizer service	`<eventName:String>`, `<callback:Function>`	target.api
`get`	Get a target.Component instance attached to an element	`<el:DOMElement>` or `<cssSelector:String>` IMPORTANT: must be a Target component	target.Component instance

Component methods

When you get a target.Component instance using .get, you will then have access to the instance's methods:

Component Method	Description	Arguments	Returns
`disable`	Disable the component. Overrides layout declarations.	None	instance
`enable`	Enable the component. Overrides layout declarations.	None	instance

Usage

Method	Usages
`show`	`target.show(myDomEl);` `target.show(myNodeList);` `target.show('#something');` `target.show('.some-things');`
`hide`	`target.hide(myDomEl);` `target.hide(myNodeList);` `target.hide('#something');` `target.hide('.some-things');`
`toggle`	`target.toggle(myDomEl);` `target.toggle(myNodeList);` `target.toggle('#something');` `target.toggle('.some-things');`
`on`	`target.on('show', myDomEl, function(el) {});` `target.on('show', myDomEls, function(el) {});` `target.on('show', '#dom-el', function(el) {});` `target.on('show', '.dom-els', function(el) {});` or `target.on('resize', function(layout, w, h) {});` `target.on('mobile', function(w, h) {});`
`off`	`target.off('show', myDomEl, function(el) {});` `target.off('show', myDomEls, function(el) {});` `target.off('show', '#dom-el', function(el) {});` `target.off('show', '.dom-els', function(el) {});` or `target.off('resize', function(layout, w, h) {});` `target.off('tablet', function(w, h) {});`
`get`	`var myComponent = target.get(myDomEl);` `var myComponent = target.get('#my-component');`
`disable`	`target.get(myDomEl).disable();`
`enable`	`target.get(myDomEl).enable();`

Events

Target.js components fire events that you can hook into using the on method. You can stop listening by using the off method.

Event Name	Fires When	Arg passed to Callback
`show`	An element is shown	`<el:DOMElement>`
`hide`	An element is hidden	`<el:DOMElement>`
`min`	A decrementer has reached its minimum value	`<input:DOMElement>`
`max`	An incrementer has reached its maximum value	`<input:DOMElement>`
`resize`	The window has resized (debounced)	`<layout:Object>`, `<width:Int>`, `<height:Int>`
`mobile`	The window has resized to a mobile layout (debounced)	`<width:Int>`, `<height:Int>`
`tablet`	The window has resized to a tablet layout (debounced)	`<width:Int>`, `<height:Int>`
`desktop`	The window has resized to a desktop layout (debounced)	`<width:Int>`, `<height:Int>`

Usage

More events to come!

Plugins

Plugin API coming soon!

Target.js

Target.js doesn't do much; but what it does, it does well. It adds functionality to your DOM elements using data-attributes.

Getting Started

Installation

Step 1. Include the minified or unminified JS file

Step 2. Initialize Target.js

Step 3. Add data-attributes on your elements

Step 4. Add styles to show/hide your elements

Configuration

Options

Example (with defaults)

Components

Show

Hide

Toggle

Clickoff

Increment/Decrement

Scrollbox

Grid

Src

Filetext

Height

Scroll

Accordion

Layouts

Usage

Example

Methods

Component methods

Usage

Events

Usage

Plugins