Component Integration

Seamless Integration

Query is deeply woven into the fabric of Semantic UI components, giving you powerful DOM manipulation capabilities at every stage of the component lifecycle. This integration eliminates the need for manual DOM querying and simplifies common component operations.

Integrated Component Framework

When building Semantic UI components, you don’t need to import or initialize Query — it’s automatically available throughout your component code from the destructured lifecycle arguments

Component Lifecycle Integration

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

Within components, you have access to both Query functions, each with a specific purpose:

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');
    });
  }
});

Best Practices for $ vs $$

Choose the right tool for your use case:

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
```
$('.tab').on('click', this.handleTabClick);
```
Use $$ when crossing component boundaries
- When accessing nested components
- When reaching out to parent or sibling components
- When you’re unsure about the DOM structure
```
$$('ui-menu .item').each((el, index) => {
  // Work with all menu items, wherever they are
});
```

Interacting with External Components

Query provides special methods for working with components from the outside, bridging the gap between components and the DOM.

Accessing Component Instances

The getComponent() method gives you direct access to a component’s 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