JavaScript

Once you have installed Franken UI, we can now include the JavaScript to control the behavior of our components.

Installation via CDN

You can include the JavaScript files on your page by adding them to the <head> section.

<script src="https://unpkg.com/[email protected]/dist/js/core.iife.js" type="module"></script>
<script src="https://unpkg.com/[email protected]/dist/js/icon.iife.js" type="module"></script>

Installation via NPM

You can import the JavaScript from franken-ui, which you installed earlier, into your app.js file.

import "franken-ui/js/core.iife";
import "franken-ui/js/icon.iife";

UIkit and reactive JavaScript frameworks

UIkit is listening for DOM manipulations and will automatically initialize, connect and disconnect components as they are inserted or removed from the DOM. That way it can easily be used with JavaScript frameworks like Vue.js and React.

Component usage

You can use UIkit components by adding uk-* or data-uk-* attributes to your HTML elements without writing a single line of JavaScript. This is UIkit’s best practice of using its components and should always be considered first.

<div uk-sticky="offset: 50;"></div>

<div data-uk-sticky="offset: 50;"></div>

Note React will work with data-uk-* prefixes only.

You can also initialize components via JavaScript and apply them to elements in your document.

var sticky = UIkit.sticky("#sticky", {
  offset: 50,
});

You can retrieve an already initialized component by passing a selector or an element as a first Argument to the component function.

var sticky = UIkit.sticky("#sticky");

Omitting the second parameter will not re-initialize the component but serve as a getter function.

Component configuration

Each component comes with a set of configuration options that let you customize their behavior. You can set the options on a per-instance level or globally.

Instance

Options can be set as shown in the following examples.

With the key: value; format:

<div uk-sticky="start: 100; offset: 50;"></div>

In valid JSON format:

<div uk-sticky='{"start": 100, "offset": 50}'></div>

As single attributes:

<div uk-sticky start="100" offset="50"></div>

Or as single attributes prefixed with data-:

<div uk-sticky data-start="100" data-offset="50"></div>

You can also pass options to the component constructor programmatically.

// Passing an options object.
UIkit.sticky(".sticky", {
  offset: 50,
  top: 100,
});

// If the component supports Primary options.
UIkit.drop("#drop", "top-left");

Precedence

Options passed via the component attribute will have the highest precedence, followed by single attributes and then JavaScript.

<div uk-sticky="offset: 50;" offset="100"></div>

<!-- The offset will be 50 -->

Globally

Component options can be changed globally by extending a component. It will affect newly created instances only.

UIkit.mixin(
  {
    data: {
      offset: 50,
      top: 100,
    },
  },
  "sticky",
);

Omitting the second parameter, will apply the custom behavior to every UIkit instance created afterwards.

Programmatic use

Programmatically, components may be initialized with the element, options arguments format in JavaScript. The element argument may be any Node, selector or jQuery object. You’ll receive the initialized component as a return value. Functional Components (e.g. Notification) should omit the element parameter.

// Passing a selector and an options object.
var sticky = UIkit.sticky(".sticky", {
  offset: 50,
  top: 100,
});

// Functional components should omit the 'element' argument.
var notifications = UIkit.notification("MyMessage", "danger");

Note The options names must be in their camel-cased representation, e.g. show-on-up becomes showOnUp.

After initialization, you can get your component by calling the same initialization function, omitting the options parameter.

// Sticky is now the prior initialised components
var sticky = UIkit.sticky(".sticky");

Note Using UIkit[componentName](selector) with CSS selectors will always return the first occurrence only! If you need to access all instances do query the elements first. Then apply the getter to each element separately - UIkit[componentName](element).

Initializing your components programmatically gives you the possibility to invoke their functions directly.

UIkit.offcanvas("#offcanvas").toggle();

Any component functions and variables prefixed with an underscore are considered as part of the internal API, which may change at any given time.

Each component triggers DOM events that you can react to. For example when a Modal is shown or a Scrollspy element becomes visible.

UIkit.util.on("#offcanvas", "show", function () {
  // do something
});

The component’s documentation page lists its events.

Note Components often trigger events with the same name (e.g. ‘show’). Usually events bubble through the DOM. Check the event target, to ensure the event was triggered by the desired component.

Sometimes, components like Grid or Tab are hidden in the markup. This may happen when used in combination with the Switcher, Modal or Dropdown. Once they become visible, they need to adjust or fix their height and other dimensions.

UIkit offers several ways of updating a component. Omitting the type parameter will trigger an update event.

// Calls the update hook on components registered on the element itself, its parents and children.
UIkit.update((element = document.body), (type = "update"));

// Updates the component itself.
component.$emit((type = "update"));

If you need to make sure a component is properly destroyed, for example upon removal from the DOM, you can call its $destroy function.

// Destroys the component. For example unbind its event listeners.
component.$destroy();

// Also destroys the component, but also removes the element from the DOM.
component.$destroy(true);

UIkit initialization

You might need to execute code after UIkit is loaded, but before it initializes its components on the page.

This hook allows you to register custom components or component mixins.

You can hook into this step in the lifecycle by listening for the uikit:init event UIkit triggers on the document.

document.addEventListener("uikit:init", () => {
  // do something
});
Customize