{"id":18828388,"url":"https://github.com/dealfonso/selectbox-ui","last_synced_at":"2026-03-10T15:03:19.094Z","repository":{"id":192359752,"uuid":"685128343","full_name":"dealfonso/selectbox-ui","owner":"dealfonso","description":"A helper to include a select box to \"any\" element in the DOM","archived":false,"fork":false,"pushed_at":"2024-09-09T11:31:06.000Z","size":10509,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-08T16:58:52.673Z","etag":null,"topics":["html","html-css-javascript","javascript","javascript-library","jquery","jquery-plugin","select"],"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/dealfonso.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-30T15:18:24.000Z","updated_at":"2024-11-10T15:24:08.000Z","dependencies_parsed_at":"2024-09-09T12:36:52.184Z","dependency_job_id":null,"html_url":"https://github.com/dealfonso/selectbox-ui","commit_stats":null,"previous_names":["dealfonso/selectbox-ui"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/dealfonso/selectbox-ui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dealfonso%2Fselectbox-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dealfonso%2Fselectbox-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dealfonso%2Fselectbox-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dealfonso%2Fselectbox-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dealfonso","download_url":"https://codeload.github.com/dealfonso/selectbox-ui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dealfonso%2Fselectbox-ui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30338587,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T15:02:55.010Z","status":"ssl_error","status_checked_at":"2026-03-10T15:02:36.911Z","response_time":106,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["html","html-css-javascript","javascript","javascript-library","jquery","jquery-plugin","select"],"created_at":"2024-11-08T01:24:52.574Z","updated_at":"2026-03-10T15:03:18.644Z","avatar_url":"https://github.com/dealfonso.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SelectBox User Interface for Web Pages (SelectBoxUI)\n\nThis library provides a user interface to make a visual selection of a rectangular area in an element of a Web page. The effect is shown in the following image:\n\n![SelectBoxUI Example](img/selectboxui-example.png)\n\nThen the user can move the selection, resize it, and get the coordinates of the selection as in the next animation:\n\n![SelectBoxUI Example](img/selectboxui-effect.gif)\n\nTo get this effect, you just need to add the `selectbox-ui.js` script and `selectbox-ui.css` style sheet to your Web page and add the `data-selectboxui` attribute to the element you want to add the effect to. For example:\n\n```html\n\u003cscript src=\"selectbox-ui.js\"\u003e\u003c/script\u003e\n\u003clink href=\"selectbox-ui.css\" rel=\"stylesheet\"/\u003e\n...\n\u003cdiv data-selectboxui\u003e\n    \u003cimg src=\"https://picsum.photos/400/200\" data-selectboxui class=\"mx-auto\" data-selectboxui-initial-box=\"25%\"\u003e\n\u003c/div\u003e\n```\n\nAlternatively, you can either use the `selectBoxUI` function (which will be defined in the window upon including the library) or use the _jQuery_ call `$('img').selectBoxUI()` to add the effect to the element.\n\nThe library is written in JavaScript and it is compatible with [jQuery](https://jquery.com/) (although it is not needed). It is distributed under the [MIT License](https://opensource.org/licenses/MIT).\n\n## Usage\n\nTo use the library, you just need to include the `selectbox-ui.js` file in your Web page. You can download it from the [GitHub repository](https://github.com/dealfonso/selectbox-ui) or get it from the CDN:\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/gh/dealfonso/selectbox-ui@1.0/dist/selectbox-ui.min.js\"\u003e\u003c/script\u003e\n\u003clink href=\"https://cdn.jsdelivr.net/gh/dealfonso/selectbox-ui@1.0/dist/selectbox-ui.min.css\u003e\" rel=\"stylesheet\"/\u003e\n```\n\n### Declarative HTML Version\n\nThe declarative version is the easiest way to use the library. You just need to add the `data-selectboxui` attribute to the element you want to add the effect to. For example:\n\n```html\n\u003cimg src=\"https://picsum.photos/400/200\" class=\"mx-auto\" data-selectboxui\u003e\n```\n\nIt is also possible to customize the effect by adding the `data-selectboxui-*` attributes to the element. For example:\n\n```html\n\u003cimg src=\"https://picsum.photos/400/200\" class=\"mx-auto\" data-selectboxui data-selectboxui-initial-box=\"25%\" data-selectboxui-no-focus\u003e\n```\n\nThe available options are described in the [Options](#options) section.\n\n### Using in Javascript\n\nYou can use the global `selectBoxUI` function to add the effect to an element. The function accepts two parameters:\n\n- `element`: Element to add the effect to. It can be a DOM element e.g. obtained using `document.querySelector(\"div\")`.\n- `options`: Object with the options to customize the effect. The available options are described in the [Options](#options) section.\n\nOnce an element has the effect, it will have a `selectBoxUI` property which is an object that enables to control the effect. An example of usage is the following:\n\n```javascript\nvar element = document.querySelector(\"div\");\nelement.selectBoxUI.set(\"10% 20% 30% 40%\");\nelement.selectBoxUI.disable();\n```\n\nThe available commands are:\n\n- `enable`: Enables the visual elements of the select box (i.e. if they are over any part of the underlying components, they will have priority over them and the user interaction will not reach to these underlying components).\n- `disable`: Disables the visual elements of the select box (i.e. even if they are over any part of the underlying components, they will not have priority over them and the user interaction will reach to these underlying components)\n- `show`: Shows the visual elements of the select box.\n- `hide`: Hides the visual elements of the select box.\n- `set`: Sets the selection box to a new position. The parameter is a string with any of the accepted formats `left top right bottom`, `horizontal vertical` or `size` (see [Selection Box format](#selection-box-format)).\n- `get`: Gets the selection box position. The result is an object with the properties `left`, `top`, `right` and `bottom`.\n\n### Using in jQuery\n\nIf you are using [jQuery](https://jquery.com/), you can use the `selectBoxUI` function to add the effect to an element, and to interact with the element that has the effect. E.g.: \n\n```javascript\n$('div').selectBoxUI({initialBox: \"10% 20% 30% 40%\"});\n$('div').selectBoxUI(\"enable\");\n```\n\nWhen adding the effect to an element, the function accepts one parameter which is an object with the options to customize the effect. The available options are described in the [Options](#options) section.\n\nOnce an element has the effect, the jQuery `selectBoxUI` plugin enables the following commands: `enable`, `disable`, `show`, `hide`, `set` and `get`. The commands are the same as in the [Using in Javascript](#using-in-javascript) section, and are used passing the command as a string to the `selectBoxUI` function. E.g.:\n\n```javascript\n$('div').selectBoxUI(\"enable\");\n```\n\nIn the case of the `set` command, the parameter is a string with any of the accepted formats `left top right bottom`, `horizontal vertical` or `size` (see [Selection Box format](#selection-box-format)). E.g.:\n\n```javascript\n$('div').selectBoxUI(\"set\", \"10% 20% 30% 40%\");\n```\n\n## Selection Box\n\nThe selection box is the area that is selected by the user. It is defined by the top-left and bottom-right corners. The selection box is defined by the following properties:\n\n- `left`: Distance from the left side of the element to the left side of the selection box.\n- `top`: Distance from the top side of the element to the top side of the selection box.\n- `right`: Distance from the right side of the element to the right side of the selection box.\n- `bottom`: Distance from the bottom side of the element to the bottom side of the selection box.\n- `width`: Width of the element.\n- `height`: Height of the element.\n\nThe selection box can be set using the `set` command or the `initialBox` option. The selection box can be retrieved using the `get` command.\n\n### Selection Box format\n\nYou can use different formats to specify the size of the selection box:\n\n1. `left top right bottom`: defines the box, with coordinates taken from the top-left of the element.\n2. `horizontal vertical`: defines the box by using the distance from the top-left and the bottom-right. e.g. `10 20` will be interpreted as `10 20 -10 -20`.\n3. `size`: defines the box by using the same size for all the sides. e.g. `10` will be interpreted as `10 10 -10 -10`.\n\nEach of the coordinates can be expressed in pixels or in percentages. e.g. `10 20 30 40` or `10% 20% 30% 40%`. The origin is the top-left corner of the element.\n\nIf any of the values is negative, it will be interpreted as the size from the bottom or right side. e.g. `10 20 -30 -40` will be interpreted as `10 20 \u003cwidth\u003e-30 \u003cheight\u003e-40`.\n\n## Options\n\nWhen creating a SelectBoxUI, you can pass a set of options to customize the effect. The options can be passed as an object to the `selectBoxUI` function or as `data-selectboxuiui-*` attributes to the element. The following options are available:\n\n- `initialBox`: Initial size of the selection box. If not specified, the initial box size will cover all the space.\n- `wrapperClass`: Class to add to the wrapper of the selection box. If not specified, the default value is `sb-selectbox-wrapper`.\n- `wrapperId`: Id to add to the wrapper of the selection box. If not specified, the default value is `null` (means that it will not add set id).\n- `addFocus`: Whether to add an active _focus section_ to the element when the selection box. The active _focus section_ means that it can be moved in the selection box, and the user interaction will not reach to the underlying elements. If not specified, the default value is `true`.\n- `addBorders`: Whether to add _active borders_ that enable to adjust the selection box. If not specified, the default value is `true`.\n- `addCorners`: Whether to add _active corners_ that enable to adjust the selection box. If not specified, the default value is `true`.\n- `addSides`: Whether to add _sides_ that adds an effect of opacity to the part which is not selected. If not specified, the default value is `true`.\n- `addClasses`: Whether to add classes of the element to the selection box wrapper (the idea is to get profit from css stylesheets for the wrapper to make the resulting selection box as similar to the original component as possible). If not specified, the default value is `true`.\n- `borderWidth`: Width of the borders of the selection box. The width means the size for the active borders, corners, etc., but that width will not have a visual effect on the result (unless tweaking the css components). If not specified, the default value is `5`.\n- `resizeObserver`: Whether to use the [ResizeObserver](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver) to detect size changes in the element. If not specified, the default value is `true`.\n- `modifySizes`: Whether to modify the sizes of the element to adapt it to the wrapper's size. If not specified, the default value is `true`.\n\nIn the declarative version, the options can be passed as `data-selectboxuiui-*`::\n\n- `data-selectboxuiui-initial-box`: Sets the value of `initialBox`.\n- `data-selectboxuiui-wrapper-class`: Sets the value of `wrapperClass`.\n- `data-selectboxuiui-wrapper-id`: Sets the value of `wrapperId`.\n- `data-selectboxuiui-no-focus`: Sets the value of `addFocus` to `false`.\n- `data-selectboxuiui-no-borders`: Sets the value of `addBorders` to `false`.\n- `data-selectboxuiui-no-corners`: Sets the value of `addCorners` to `false`.\n- `data-selectboxuiui-no-sides`: Sets the value of `addSides` to `false`.\n- `data-selectboxuiui-no-add-classes`: Sets the value of `addClasses` to `false`.\n- `data-selectboxuiui-border-width`: Sets the value of `borderWidth`.\n- `data-selectboxuiui-no-resize-observer`: Sets the value of `resizeObserver` to `false`.\n- `data-selectboxuiui-no-modify-sizes`: Sets the value of `modifySizes` to `false`.\n\n### Default options\n\nThe default options can be changed by modifying the `selectBoxUI.defaults` object. For example, to change the default initial box to `10%`, you can use the following code, which will change the default for all the elements that have the effect:\n\n```javascript\nshowsource.defaults.initialBox = \"10%\";\n```\n\nAdditionally, it is possible to set multiple default values at once, by setting `showsource.defaults` to an options object. For example, to disable the focus and the corners by default, you can use the following code:\n\n```javascript\nshowsource.defaults = {\n    addFocus: false,\n    addCorners: false\n};\n```\n\n## Styles\n\nThe library adds a set of styles to the elements that build the selection box. The styles are added to the element itself and to the wrapper of the selection box. The following styles are added to the elements:\n\n- `sb-element`: Class for any object that is part from the selection box.\n- `sb-selectbox-wrapper`: Class for the wrapper of the selection box.\n- `sb-border`: Class of the borders of the selection box.\n- `sb-border-top`, `sb-border-right`, `sb-border-bottom`, `sb-border-left`: Classes for each of the borders of the selection box.\n- `sb-corner`: Class of the corners of the selection box.\n- `sb-corner-topleft`, `sb-corner-topright`, `sb-corner-bottomright`, `sb-corner-bottomleft`: Classes for each of the corners of the selection box.\n- `sb-side`: Class of the sides of the selection box.\n- `sb-side-top`, `sb-side-right`, `sb-side-bottom`, `sb-side-left`: Classes for each of the sides of the selection box.\n- `sb-focus`: Class of the focus section of the selection box.\n- `sb-resizing`: Class of the selection box element when it is being used to resize the selection box. i.e. if the user is using the left border to resize the selection box, the `sb-resizing` class will be added to the left border and only to the left border.\n\n### Additional styles\n\nThe library also adds some additional styles that add some effects to the selection box. The following styles are added to the elements:\n\n- `sb-bounce`: Is a class that makes that the borders of the selection box bounce for 2 seconds. It is designed to be used to show the user that there is a selection box. (This should be added to the wrapper element or the container of the selection box).\n- `sb-borders-fixed`: Is a class that makes that the guides of the borders of the selection box are shown. If this class is not added, the guides will be hidden while they are not being used to resize the selection box. (This should be added to the wrapper element or the container of the selection box).\n- `sb-ignore-mouse`: Is a class that makes that the mouse events are ignored by the element. This class is added when a selection box is disabled. This can be added to any element that you want to ignore the mouse events.\n- `sb-hidden`: Is a class that makes that the element is hidden. This class is added when a selection box is hidden. This can be added to any element that you want to hide.\n\n### Customizing the Styles\n\nThe default style is defined in the `selectbox-ui.css` file, but you can override it by defining your own style sheet. The next example will add a dark-red background to the selection box:\n\n```css\n.sb-side-box {\n    background-color: #633;\n}\n```\n\n## Events\n\nThe library triggers some events that can be used to control the effect. The events are triggered in the element that has the effect. The following events are available:\n\n- `selectboxui-changed`: Is triggered when the selection box is changed either by the interaction of the user or by using the API.\n- `selectboxui-resize-start`: Is triggered when the box starts to be resized because of the interaction of the user (i.e. using a side, corner, etc.).\n- `selectboxui-resize`: Is triggered when the box is being resized because of the interaction of the user (i.e. using a side, corner, etc.).\n- `selectboxui-resize-end`: Is triggered when the box ends to be resized because of the interaction of the user (i.e. using a side, corner, etc.).\n- `selectboxui-bounce-start`: Is triggered when the bounce effect starts.\n- `selectboxui-bounce-end`: Is triggered when the bounce effect ends.\n- `selectboxui-show`: Is triggered when the selection box is shown.\n- `selectboxui-hide`: Is triggered when the selection box is hidden.\n- `selectboxui-enable`: Is triggered when the selection box is enabled.\n- `selectboxui-disable`: Is triggered when the selection box is disabled.\n- `selectboxui-element-resized`:  Is triggered when it is detected that the element that has the effect has been resized, and the selection box has been adapted to the new size.\n\nEach of the events has a `detail` property which is the `selectionBoxUI` object.\n\nThe events can be listened using the `addEventListener` function. E.g.:\n\n```javascript\nvar element = document.querySelector(\"div\");\nelement.addEventListener(\"selectboxui-changed\", function(event) {\n    console.log(\"Selection box changed\");\n});\n```\n\n## Examples\n\nYou can see some examples of usage in the `examples.html` web page. You can also see the examples in action in the [GitHub Pages](https://dealfonso.github.io/selectbox-ui/) of the project.\n\n### Example 1\n\nThe following example shows how to add the effect to an image:\n\n```html\n\u003cimg src=\"https://picsum.photos/400/200\" data-selectboxui class=\"mx-auto\" data-selectboxui-initial-box=\"25%\"\u003e\n```\n\n![SelectBoxUI Example](img/selectboxui-simple.gif)\n\n### Example 2\n\nThe following example shows how to add the effect to an iframe:\n\n```html\n\u003ciframe class=\"mx-auto\" data-selectboxui data-selectboxui-initial-box=\"25%\" src=\"https://www.youtube.com/embed/9bZkp7q19f0\" width=\"560\" height=\"315\" frameborder=\"0\"\u003e\u003c/iframe\u003e\n```\n\n![SelectBoxUI Example](img/selectboxui-complex.gif)\n\nIn this example you can see a full example that uses the API to control the effect. The complete code is included in the `examples.html` file.\n\n## Known Issues\n\n### Responsiveness\n\nThe SelectBoxUI is not responsive by default, but it adds helpers to respond to size changes in the element. So if you change the size of the element (e.g. by changing the `style` or using `jQuery`), the SelectBoxUI will try to adapt to the new size.\n\nAnyway, this library tries to make its best to create the SelectBox UI, but may not get a perfect result. It is a tool to help you create a better user experience, but it is not a replacement for a good designer. So sometimes you may need to use some tweaks to get a better result:\n\n- You can use the `resizeObserver` options (or the `data-selectboxui-resize-observer`) and set it to `false` to disable the resize observer. This will prevent the SelectBoxUI from trying to adapt to the size changes, and will avoid some issues like the SelectBoxUI not being able to adapt to the size of the element.\n- You can use the `modifySizes` option (or the `data-selectboxui-modify-sizes`) and set it to `false` to avoid modifying the sizes of the element to adapt it to the wrapper's size. The default behavior is to set the element's size _100%_ to automatically adapt to the wrapper's size, but this may not be the best option in some cases and may lead to get a `0px` size and thus the object will disappear.\n\nAny help to make the SelectBoxUI responsive by default is welcome.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdealfonso%2Fselectbox-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdealfonso%2Fselectbox-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdealfonso%2Fselectbox-ui/lists"}