Query with Components

Authoring Components

When authoring a component you can use $ and $$ to access the DOM and shadow DOM in any function in your component.

Component Instance

const createComponent = ({ $ }) => ({

  // Imperatively update the DOM in your component
  activateTab(index) {
    $('.tab')
      .removeClass('active')
      .find(`[data-index="${index}]`)
        .addClass('active');
  }

  // rest of your component

});

Rendering

// access DOM after component is in page
const onRendered = ({ $, isClient }) => {
  if (isClient) {
    const $activeTab = $('.active.tab');
    const height = $activeTab.height();
    $activeTab.css('min-height', `${height}px`);
  }
};

Key Bindings

// close tab on escape key
const keys = {
  'esc'({ $ }) {
    $('.active.tab').removeClass('active');
  }
};

Event Handling

const events = {
  'click .tab'({ $, target, self }) {
    // Deactivate all tabs
    $('.tab').removeClass('active');

    // Activate clicked tab
    $(target).addClass('active');

    // Show corresponding content
    self.activateTab(index);

  }
};

$ vs $$ in Components

Use $ for internal component elements
- More efficient when you’re working within your component’s shadow DOM
- Use for most component operations that don’t cross boundaries
Use $$ when accessing nested web components
- When accessing nested components
- When reaching out to parent or sibling components
- When you’re unsure about the DOM structure

const createComponent = ({ $, $$ }) => ({
  initialize() {
    // $ queries within this component's shadow DOM
    $('.content').addClass('initialized');

    // $$ can reach outside this component or into nested components
    $$('ui-button').on('click', function() {
      console.log('Button clicked');
    });
  }
});

Accessing Components

Query provides several tools to let you access your component, view its data context and modify its functionality.

Accessing Component Instances

Use getComponent() to access methods and properties on a component instance.

// Get a reference to the button component
const tabs = $('ui-tabs').getComponent();

if (tabs) {
  const newIndex = 2;
  tabs.setActive(newIndex);
}

Component Configuration

Query can also be used to modify a components settings at run time.

settings()

settings

// Configure all buttons on the page
$('ui-button').settings({
  icon: 'arrow-right',
  primary: true,
  state: 'active'
});

This is necessary to pass in settings that can’t be serialized as attributes.

initialize()

initialize will pass in the settings after DOMContentLoaded which means it can be used before the component is in the page.

const $modal = $('ui-modal').initialize({
  closable: true,
});
showModal = () => {
  $modal.getComponent().show();
};

This is particular useful to declaratively update the settings of many components across an app.

// every button now has a checkmark icon
$('ui-button').settings({ icon: 'checkmark' });

Example

The following example creates a context-menu on right click and positions it using $ in the adjustMenuPosition method.

Next Steps

Now that you understand how Query integrates with components, explore:

Complete Component DOM guide for more details on DOM manipulation in components
Working with Shadow DOM for advanced shadow DOM techniques
Chaining techniques for efficient query operations
Browser usage for using Query outside of components

On This Page