Wondering what’s next for npm?Check out our public roadmap! »

    TypeScript icon, indicating that this package has built-in type declarations

    1.0.12 • Public • Published


    A library to make container/element queries. Add classes or execute an action once an element reaches a desired dimension.

    It listens to changes in the dimensions of an element using the ResizeObserver API.


    npm i containerq

    Basic usage

    import { ContainerQ } from "containerq";
    const cq = new ContainerQ();
    const container = document.querySelector(".container");
    cq.query(container, "width", ">", 300, "px", "container--big");

    This bit of code adds the class "container--big" to the element "container" once its width is greater than 300 pixels and removes the class if it's less than or equal to 300 pixels.


    query(element, property, comparison, breakpoint, unit, className): number

    element: Element property: "width" | "height" comparison: "=" | "<" | "<=" | ">" | ">=" breakpoint: number unit: "px" | "rem" | "em" | "%" className: string

    Adds a class to an element if a dimension (width or height) meets a condition and removes the class if the condition is not being met anymore.

    When the percentage (%) unit is used the parent element is listened for size changes too.


    const id = cq.query(container, "width", ">", 300, "px", "container--big");

    Returns a queryId, an id number that represents the condition passed to query(). Useful if you later want to remove that query or if you want to check if said query exists.

    query(element, property, comparison, breakpoint, unit, onQueryActive, onQueryInactive?): number

    element: Element property: "width" | "height" comparison: "=" | "<" | "<=" | ">" | ">=" breakpoint: number unit: "px" | "rem" | "em" | "%" onQueryActive: Function onQueryInactive?: Function

    Executes the function onQueryActive if a dimension (width or height) meets a condition. Optionally, another function, onQueryInactive, can be passed to be executed once the desired condition is not being met anymore.


    function active() {
    	console.log("I'm big")
    function inactive() {
    	console.log("I'm small")
    cq.query(container, "width", ">=", 50, "%", active, inactive);

    Returns queryId.


    queryId: number

    Stops a specific query from an element.


    element: Element

    Stops every query associated to a specific element.


    Stops every query of every element in the ContainerQ instance.

    isQuerying(queryId): QueryInfo | undefined

    queryId: number

    QueryInfo: {
        property: "width" | "height";
        comparison: "=" | "<" | "<=" | ">" | ">=";
        breakpoint: number;
        unit: "px" | "rem" | "em" | "%";
        onQueryActive: string | Function;
        onQueryInactive?: Function;
        queryId: number;
        active: boolean;

    Receives the id of a query and returns the QueryInfo object of that query. It has information about a specific query.

    Returns undefined if the id is not associated to any query or if its associated query was removed via the stopQuerying method.

    onQueryActive is a string if a className string is passed to the query method. Likewise if a function was passed then onQueryActive will be a function.

    The active property is a boolean indicating if the condition of the pertaining query is true or false at the moment.


    const id = cq.query(container, "width", ">", 300, "px", "container--big");
    console.log(cq.isQuerying(id).property) //width
    console.log(cq.isQuerying(id)) //undefined

    isQuerying(element): QueryInfo[] | undefined

    element: Element

    Takes an Element and returns an array of every QueryInfo object associated to the Element.

    Returns undefined if no queries are associated with the passed Element.


    cq.query(container, "height", "<", 10, "rem", "container--short");
    cq.query(container, "width", ">=", 550, "px", "container--wide");
    console.log(cq.isQuerying(container)) //[{...}, {...}]

    React Hook

    useCQ(elementRef, queries)

    elementRef: React.MutableRefObject<Element> queries: QueryProperties[]

    QueryProperties: {
        property: "width" | "height";
        comparison: "=" | "<" | "<=" | ">" | ">=";
        breakpoint: number;
        unit: "px" | "rem" | "em" | "%";
        onQueryActive?: string | Function;
        onQueryInactive?: Function;
        onQueryToggleState?: Function;


    import { useCQ } from  "containerq";
    function  MyComponent() {
        const [wideSize, setWideSize] = useState(false);
        const [shortSize, setShortSize] = useState(false);
        const  divRef= useRef();
        useCQ(divRef, [
    	    { property: "width", comparison: ">", breakpoint: 60, unit: "%", onQueryToggleState: setWideSize },
    	    { property: "height", comparison: "<=", breakpoint: 30, unit: "%", onQueryToggleState: setShortSize }
        return (
    	    <div ref={divRef}>
    		    <SubComponent1 isWideSize={wideSize} />
    		    <SubComponent2 isWideSize={wideSize} />
    		    <SubComponent3 isShortSize={shortSize} />
    // The first two subcomponents react to the parent container being wide
    // The last subcomponent reacts to the parent container being short

    The queries object of type QueryProperties has properties very similar to the query method's parameters. The only difference is the property onQueryToggleState which takes a function that's called with true as an argument when the query's condition is being met, otherwise is called with false as the argument.

    The idea is to use onQueryToggleState alongside useState but you could come up with different ways of using it.

    There is no need to create a ContainerQ instance when using the hook because an instance is created when useCQ is imported. Also, the queries associated with the hook are cleared automatically when the component gets unmounted.


    npm i containerq

    DownloadsWeekly Downloads






    Unpacked Size

    22.4 kB

    Total Files


    Last publish


    • avatar