{"id":17345292,"url":"https://github.com/bcinarli/uxr","last_synced_at":"2025-04-14T20:46:19.379Z","repository":{"id":51775079,"uuid":"111511153","full_name":"bcinarli/uxr","owner":"bcinarli","description":"A set of JavaScript utilities for selecting and modifying elements","archived":false,"fork":false,"pushed_at":"2021-05-10T03:27:17.000Z","size":950,"stargazers_count":28,"open_issues_count":3,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-28T09:03:49.293Z","etag":null,"topics":["chaining-callables","dom","dom-manipulation","javascript","plugins","selector"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bcinarli.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-11-21T06:54:52.000Z","updated_at":"2024-05-23T02:43:44.000Z","dependencies_parsed_at":"2022-08-31T20:02:22.217Z","dependency_job_id":null,"html_url":"https://github.com/bcinarli/uxr","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcinarli%2Fuxr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcinarli%2Fuxr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcinarli%2Fuxr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcinarli%2Fuxr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bcinarli","download_url":"https://codeload.github.com/bcinarli/uxr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248960738,"owners_count":21189987,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chaining-callables","dom","dom-manipulation","javascript","plugins","selector"],"created_at":"2024-10-15T16:30:20.720Z","updated_at":"2025-04-14T20:46:19.361Z","avatar_url":"https://github.com/bcinarli.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"http://uxrocket.io/browsers/uxrocket.png\" width=\"64\" align=\"right\" /\u003e\n\n# UXR\n[![npm][npm]][npm-url]\n[![tests][tests]][tests-url]\n[![coverage][cover]][cover-url]\n[![devDependencies Status][dm]][dm-url]\n[![Maintainability][cc]][cc-url]\n[![Open Source Love][os]][os-url]\n[![PRs Welcome][pr]][pr-url]\n\n\nA minimal in mind library for DOM related routines and element selections. UXR wraps some most used methods like CSS Classes, Event Management, Data Management, Attribute selections/updates. Supports chaining and plugins.\n\nUXR has the philosophy of fewer code and low file size. Because of this, widely supported ES6 codes are not transpiled to ES5 versions and not trying to cover all JavaScript methods which are normally written without much effort. UXR provides easy to wrappers for normally complex once.\n\n## Browser Support\n| Browser | \u003cimg src=\"http://uxrocket.io/browsers/chrome.png\" width=\"24\" /\u003e | \u003cimg src=\"http://uxrocket.io/browsers/firefox.png\" width=\"24\" /\u003e | \u003cimg src=\"http://uxrocket.io/browsers/opera.png\" width=\"24\" /\u003e | \u003cimg src=\"http://uxrocket.io/browsers/safari.png\" width=\"24\" /\u003e | \u003cimg src=\"http://uxrocket.io/browsers/edge.png\" width=\"24\" /\u003e |\n| ------- | ----------------- | ------------------- | --------------- | ----------------- | ------------- |\n| Version  | 49+  | 36+ | 37+ | 10+ | 12+ |\n\n## How To Use\nYou can install UXR via Node package managers\n``` js\n$ npm install uxr\n// or\n$ yarn add uxr\n```\n\nOr you can directly include you `dist` files to your project after downloading the desired version.\n\nAfter adding the `dist/uxr.min.js` to your page, you can select an element set from DOM and start to manipulate/modify the selection.\n\n### Loading UXR methods\nYou can define UXR methods to run when page loads and content ready. Or run when needed.\n\n``` js\nuxr.ready(function(){\n    // inner functions automatically runs when document is ready\n});\n\nuxr.load(function(){\n    // inner functions automatically runs when document is fully loaded\n});\n```\n\n### Element Selection\nEvery `uxr` methods starts with element selections. Basically selection uses `querySelectorAll` getting element from DOM or Arrays.\n\n``` js\n// selecting an element with querySelectorAll supported selector strings\nuxr(selector);\n\n// getting an array as selector\nuxr([0, 1, 2, 3])\n```\n\n### Chaining\n`uxr` methods supports chaining. So you can call `uxr` methods one after another.\n\n``` js\nuxr(selector)\n    .addClass('hello')\n    .find('a')\n    .on('click', e =\u003e { \n        e.preventDefault();\n        console.log('Hello World!')\n    })\n    .end()\n    .attr('id', 'my-id');\n```\n\n### Attribute Manipulation\nWith `uxr(selector).attr()` methods you can get an attribute's value or set a value in HTML tags\n\n``` js\nlet el = uxr(selector);\n\n// get the ID\nlet id = el.attr('id');\n// getAttr method is an alias to attr(name)\nlet id = el.getAttr('id');\n\n// set the ID\nel.attr('id', 'new-id');\n// setAttr method is an alias to attr(name, value);\nel.setAttr('id', 'new-id');\n\n// get a data-attr value\n// the following both samples gets the same attribute\nel.attr('data-attr');\nel.attr('dataAttr');\n\n// Remove an attribute from HTML\nel.removeAttr('id');\nel.removeAttribute('id');\n```\n\nThere are some, easy to use - easy to remember attribute methods\n\n\n* `uxr(selector).src(value)` : if you send the `value` it sets the `src` of the element. Otherwise returns the `src` value. \n* `uxr(selector).href(value)` : if you send the `value` it sets the `href` value of the anchor with the new one. Otherwise returns the `href` value. \n\n### Props\nWith `uxr(selector).prop()` methods you can get an DOM node element's properties. This is different than attr methods where it get native elements properties rather than HTML attributes.\n\n``` js\nlet el = uxr(selector);\n\n// get a property\nlet innerText = el.prop('innerText');\n\n// set a property\nel.prop('innerText', 'New Text');\n```\n\nThere are some, easy to use - easy to remember property methods\n* `uxr(selector).text(value)` : if you send the `value` it sets the `innerText` value with the new one. Otherwise returns the `innerText` value. \n* `uxr(selector).html(value)` : if you send the `value` it sets the `innerHTML` value with the new one. Otherwise returns the `innerHTML` value. \n* `uxr(selector).value(value)` : if you send the `value` it sets the value of form elements with the new one. Otherwise returns the value of the form element. \n\n### Class Manipulation\nWith `uxr` it is easier to add/remove or check classes. All for class manipulation methods supports multiple class names separated with space and setting class starting with dot (`.`) \n\n``` js\nlet el = uxr(selector);\n\n// add a new css class\nel.addClass('new-class');\nel.addClass('.new-class');\n\n// add multiple classes at once\nel.addClass('.a set .of classes');\nel.addClass(['array', 'of', 'classes']);\n\n// remove a css class\nel.removeClass('old-class');\nel.removeClass('.old-class');\n\n// toggles a class\nel.toggleClass('class-to-toggle');\nel.toggleClass('.class-to-toggle');\n\n// checks if has the class or not\nel.hasClass('class-to-check');\nel.hasClass('.class-to-check');\n```\n\n### Data Attributes\nData method gets or sets a data attribute. If `dataset` supported, gets or sets values via `dataset` otherwise, uses the `getAttribute` method to get value. Both supports _camelCase_ and _dashed_ attribute names.\n\n``` js\nlet el = uxr(selector);\n\n// get data value\nel.data('uxr-demo');\nel.data('uxrDemo');\n\n// set data value\nel.data('uxr-demo', true);\nel.data('uxrDemo', true);\n```\n\n### Events\nDOM events can easily attached to elements. Named events and anonymous events supported while attaching the event. Also _triggering_ an event is possible. \n\n#### Add Events\n\n``` js\nlet myFunc = (e) =\u003e { console.log(e.currentTarget);}\n\n// attach an event\nuxr(selector).on('click', myFunc);\n\n// attach an event to child\nuxr(selector).on('click', '.clickable', myFunc);\n\n// attach multiple event\nuxr(selector).on('input focus', e =\u003e { console.log(e.currentTarget.value); }\n```\n\n#### Remove Events\n\n``` js\n// remove all click events\nuxr(selector).off('click');\n\n// remove only click event attached with myFunc\nuxr(selector).off('click', myFunc);\n\n// remove events attached with an anonymous function\nuxr(selector).off('input focus', e =\u003e { console.log(e.currentTarget.value); }\n```\n\n#### Single Run Events\nSingle Run events are only run once then remove itself from the element.\n\n``` js\n// run once\nuxr(selector).once('touchend', e =\u003e { console.log('touch ended'); })\n```\n\n#### Trigger Events\nNative and custom events can be triggered by using trigger method. Similar to event bindings, event trigger can be triggered on children elements. Despite event binding, where you can bind multiple events at once, you can trigger one event at a time.\n\n``` js\n// trigger a click event\nuxr(selector).trigger('click');\n\n// trigger a custom event\nuxr(selector).trigger('custom');\n\n// trigger a focus event in children\nuxr(selector).trigger('focus', 'input[type=text]');\n\n// trigger event with params\nuxr(selector).trigger('click', {custom: 'params', another: {custom: 'paramater'}});\n\n// trigger event with params in children\nuxr(selector).trigger('blur', 'textarea', {custom: 'params', another: {custom: 'paramater'}});\n```\n\n### Wrapper Methods\nWith wrapper methods, you can wrap element or elements to a new parent or unwrap them.\n\n``` js\nlet single = uxr('.single-element');\nlet list = uxr('.list-element');\n\n// wrap element\nsingle.wrap('div');\n\n// wrap all elements in a single parent\nlist.wrapAll('\u003cul /\u003e');\n\n// Unwrap the parent\nsingle.unwrap();\n```\n\nUnwrap removes the immediate parent. If a selector also defined for the unwrap as `el.unwrap(selector)`, it check if the immediate parent matches the selector.\n\nFor wrapper definitions, you can define wrapper string without brackets, with brackets, with attributes etc. \nAll of the following strings are valid wrapper definitions\n\n* `div` _only name of the tag_\n* `\u003cdiv\u003e` _tag name with brackets_\n* `\u003cdiv /\u003e`\n* `\u003cdiv\u003e\u003c/div\u003e`\n* `\u003cdiv class=\"wrapper\" /\u003e` _tag name with attributes_\n* `\u003cdiv class='wrapper' id=\"container\"\u003e\u003c/div\u003e`\n\n### Element Insertions\nBy using `before`, `after`, `prepend` and `append` you can control where to insert newly created elements. Also with `replaceWith` you can swap the element with a new one.\n\n``` js\nlet el = uxr('.container');\n\n// adds an element before selection\nel.before('\u003cp\u003eThis will be before of \"el\"\u003c/p\u003e');\nel.before(uxr('#new'));\n\n// adds an element after selection\nel.after('\u003cp\u003eThis will be after of \"el\"\u003c/p\u003e');\nel.after(uxr('#new'));\n\n// appends an element add the end of selection's content\nel.append('\u003cp\u003eThis will be at the end of \"el\"\u003c/p\u003e');\nel.append(uxr('#new'));\n\n// appends an element add the beginning of selection's content\nel.prepend('\u003cp\u003eThis will be at the beginning of \"el\"\u003c/p\u003e');\nel.prepend(uxr('#new'));\n\n// replaces the element with new one\nel.replaceWith('\u003cdiv id=\"replaced\"\u003ePrevious element replaced\u003c/div\u003e');\n```\n\n### Filtering and Finding\nFiltering methods help to find or filter elements in a UXR object.\n\n``` js\n// create a subset of elements in a UXR object\nuxr(selector).filter(anotherSelector);\n\n// create a subset of elements that a not matched the selector in a UXR object\nuxr(selector).not(anotherSelector);\n\n// find / select children elements in a UXR object\n// has method is an alias to find\nuxr(selector).find(childrenSelector);\nuxr(selector).has(childrenSelecotr);\n```\n\n### Traversing\nWith traversal methods, you can find adjacent or parent elements accordingly. Almost all traversal methods returns a `uxr` object. You can return the previous `uxr` by chaining `end()` \n\n``` js\n\nlet el = uxr('li');\n\n// get the immediate parent\nel.closest();\n\n// get the grandparent\nel.closest().closest();\n\n// filter the parents and get the first matched\nel.closest(selector);\n\n// get the next sibling\nel.next();\n\n// get the next sibling if matched \nel.next(selector);\n\n// get the previous sibling\nel.prev();\n\n// get the previous sibling if matched\nel.prev(selector);\n\n// get the first element in uxr object - selection\nel.first();\n\n// get the last element in uxr object - selection\nel.last();\n\n// get the immediate parent\nel.parent();\n\n// get the immediate parent if matched to selector\nel.parent(selector);\n\n// get the all children element\nel.children();\n\n// get the all matched children\nel.children(selector);\n\n// get the all siblings\nel.siblings();\n\n// get the all matched siblings\nel.siblings(selector);\n``` \n\n### CSS\n`css` method helps to set or get style attributes of the elements.\n\n``` js\nlet el = uxr(selector);\n\n// get a style property\nel.css('display'); // returns the display property value\n\n// get a list of style properties\n// returns an object with listed values. \n// note that, you can ask for properties both kebap-case and camelCase\nel.css(['display', 'margin', 'padding-top', 'borderLeft']); \n// returns {display: value, margin: value, paddingTop: value, borderLeft: value}\n\n// sets or updates a single property\nel.css('padding', '10px');\nel.css('background-color', '#ccc');\nel.css('backgroundSize', '100% auto');\n\n// sets or updates a list of properties\n// note that, you can send a object contains property:value pairs\nel.css({width: '100px', height: '50px', 'margin-bottom': '5px'});\n```\n\n### Dimensions\nDimension related methods returns or sets content width or height according to dimension method. Except setting `width` and `height` methods, all other usages break the chaining.\n\n``` js\nlet el = uxr(selector);\n\n// returns the first elements content width\n// note that: this return only the content width, no-border, no-padding, no-margin\nel.width();\nel.contentWidth(); // alias method\n\n// sets the width of elements in the uxr object.\n// similar method to el.css('width', value); \nel.width('100px');\nel.contentWidth('100%');\n\n// returns the clientWidth of the first element\n// note that: this is only differs from width method with addition of padding\nel.innerWidth();\nel.clientWidth(); // alias method\n\n\n// returns the offsetWidth of the first element\n// note that: this calculates width with border, padding and content-width altogether\nel.outerWidth();\nel.offsetWidth(); // alias method\n\n// returns the offsetWidth of the first element including margins\n// note that: this calculates width with margin, border, padding and content-width altogether\nel.outerWidth(true);\nel.offsetWidth(true); // alias method\n\n// returns the first elements content height\n// note that: this return only the content height, no-border, no-padding, no-margin\nel.height();\nel.contentHeight(); // alias method\n\n// sets the height of elements in the uxr object.\n// similar method to el.css('height', value); \nel.height('100px');\nel.contentHeight('100%');\n\n// returns the clientHeight of the first element\n// note that: this is only differs from width method with addition of padding\nel.innerHeight();\nel.clientHeight(); // alias method\n\n\n// returns the offsetHeight of the first element\n// note that: this calculates height with border, padding and content-height altogether\nel.outerHeight();\nel.offsetHeight(); // alias method\n\n// returns the offsetHeight of the first element including margins\n// note that: this calculates height with margin, border, padding and content-height altogether\nel.outerHeight(true);\nel.offsetHeight(true); // alias method\n```\n\n### Cloning\nClone methods, clones the nodes in a UXR object. \n\n``` js\nlet el = uxr(selector);\n\n// clones the all elements in uxr object\nlet clone = el.clone();\n\n// deep clones (child elements and inner contents) the all elements in uxr object\nlet cloneDeep = el.clone(true);\n```\n\n[npm]: https://img.shields.io/npm/v/uxr.svg\n[npm-url]: https://npmjs.com/package/uxr\n\n[tests]: http://img.shields.io/travis/bcinarli/uxr.svg\n[tests-url]: https://travis-ci.org/bcinarli/uxr\n\n[cover]: https://codecov.io/gh/bcinarli/uxr/branch/master/graph/badge.svg\n[cover-url]: https://codecov.io/gh/bcinarli/uxr\n\n[os]:https://badges.frapsoft.com/os/v2/open-source.svg?v=103\n[os-url]:(https://github.com/ellerbrock/open-source-badges/)\n\n[pr]:https://img.shields.io/badge/PRs-welcome-brightgreen.svg\n[pr-url]:http://makeapullrequest.com\n\n[cc]:https://api.codeclimate.com/v1/badges/2da503653af06036b031/maintainability\n[cc-url]: https://codeclimate.com/github/bcinarli/uxr/maintainability\n\n[dm]:https://david-dm.org/bcinarli/uxr/dev-status.svg\n[dm-url]:https://david-dm.org/bcinarli/uxr?type=dev\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbcinarli%2Fuxr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbcinarli%2Fuxr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbcinarli%2Fuxr/lists"}