{"id":13990168,"url":"https://github.com/bramstein/jlayout","last_synced_at":"2025-10-23T22:58:11.299Z","repository":{"id":65644130,"uuid":"756184","full_name":"bramstein/jlayout","owner":"bramstein","description":"JavaScript layout algorithms","archived":false,"fork":false,"pushed_at":"2012-11-20T07:29:53.000Z","size":185,"stargazers_count":287,"open_issues_count":4,"forks_count":54,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-04-12T23:03:55.859Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://www.bramstein.com/projects/jlayout/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bramstein.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2010-07-04T11:12:26.000Z","updated_at":"2025-02-25T23:47:13.000Z","dependencies_parsed_at":"2023-02-02T08:00:27.183Z","dependency_job_id":null,"html_url":"https://github.com/bramstein/jlayout","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bramstein/jlayout","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bramstein%2Fjlayout","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bramstein%2Fjlayout/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bramstein%2Fjlayout/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bramstein%2Fjlayout/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bramstein","download_url":"https://codeload.github.com/bramstein/jlayout/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bramstein%2Fjlayout/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274407330,"owners_count":25279267,"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","status":"online","status_checked_at":"2025-09-10T02:00:12.551Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2024-08-09T13:02:24.840Z","updated_at":"2025-10-23T22:58:06.275Z","avatar_url":"https://github.com/bramstein.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"## jLayout — JavaScript Layout Algorithms\n\nThe jLayout JavaScript library provides layout algorithms for laying out components. A component is an abstraction; it can be implemented in many ways, for example as items in a HTML5 Canvas drawing or as HTML elements. The jLayout library allows you to focus on drawing the individual components instead of on how to arrange them on your screen.\n\nThe library currently provides four layout algorithms: `border`, which lays out components in five different regions; `grid`, which lays out components in a user defined grid, `flex-grid` which offers a grid with flexible column and row sizes, and `flow` which flows components in a user defined direction. Using the `grid` and `flex-grid` algorithms you can also create horizontal and vertical layouts. A [jQuery plugin](jquery-plugin.html) to lay out HTML elements is also available.\n\n## Usage\n\nWe start with the definition of a component; a component is something that has a minimum size, a preferred size, and a maximum size. It also has a method to set its size and position. A container is a component that contains other components and lays them out according to a layout algorithm (which are provided in the jLayout library.) Components need to satisfy the following interface requirements in order to be used with the layout algorithms.\n\n\u003cdl\u003e\n    \u003cdt\u003ebounds()\u003c/dt\u003e\n    \u003cdd\u003eReturns the component's position and size as a value object with properties `x`, `y`, `width` and `height`. All properties should be present in the returned object.\u003c/dd\u003e\n    \n    \u003cdt\u003ebounds(value)\u003c/dt\u003e\n    \u003cdd\u003eSet the position and size of a component by using a value object with properties `x`, `y`, `width` and `height`. The individual properties are all optional, it is thus legal to supply an empty object, or any combination of properties.\u003c/dd\u003e\n\n    \u003cdt\u003epreferredSize()\u003c/dt\u003e\n    \u003cdd\u003eReturns the component's preferred size (i.e. the size it wishes to have) as an object with properties `width` and `height`. This is only a hint, there is no guarantee the component will get the size it prefers.\u003c/dd\u003e\n    \n    \u003cdt\u003eminimumSize()\u003c/dt\u003e\n    \u003cdd\u003eReturns the component's minimum size (i.e. the size it should at least have) as an object with properties `width` and `height`.\u003c/dd\u003e\n    \n    \u003cdt\u003emaximumSize()\u003c/dt\u003e\n    \u003cdd\u003eReturns the component's maximum size (i.e. the size it should stay below or equal to) as an object with properties `width` and `height`.\u003c/dd\u003e\n\n    \u003cdt\u003eisVisible()\u003c/dt\u003e\n    \u003cdd\u003eReturns `true` if the component is visible and should be taken into account when calculating the layout. Returns `false` otherwise.\u003c/dd\u003e\n    \n    \u003cdt\u003einsets()\u003c/dt\u003e\n    \u003cdd\u003eReturns the offset between a container and its contents as an object with properties: `top`, `bottom`, `left`, and `right`.\u003c/dd\u003e\n    \n    \u003cdt\u003edoLayout()\u003c/dt\u003e\n    \u003cdd\u003eCalls the `layout` method on the layout algorithm used to lay out the component (container) it is called on. If the component is not a container (and does not have a layout algorithm) this method can be left empty.\u003c/dd\u003e\n\u003c/dl\u003e\n\nNote that the distinction between containers and components is artificial, both implement the same interface.\n\n## Layout Algorithms\n\nAll algorithms are in the `jLayout` namespace and implement the following interface.\n\n\u003cdl\u003e\n    \u003cdt\u003epreferred(container)\u003c/dt\u003e\n    \u003cdd\u003eReturns the preferred size of the container and its children according to the layout algorithm.\u003c/dd\u003e\n    \n    \u003cdt\u003eminimum(container)\u003c/dt\u003e\n    \u003cdd\u003eReturns the minimum size the container and its children are allowed to have according to the layout algorithm.\u003c/dd\u003e\n    \n    \u003cdt\u003emaximum(container)\u003c/dt\u003e\u003cdd\u003e\nReturns the maximum size the container and its children are allowed to have according to the layout algorithm.\u003c/dd\u003e\n\n    \u003cdt\u003elayout(container)\u003c/dt\u003e\n    \u003cdd\u003ePerforms the layout according to the algorithm; resizing and positioning children if necessary.\u003c/dd\u003e\n\u003c/dl\u003e\n\nThe layout method will not resize the container to accommodate its children's preferred size. If a resize is desired, set the bounds of the container to its preferred size. The example below shows both ways of laying out a container; resizing the children to fit in the container, and resizing the container to fit the children.\n\n    // create a layout algorithm\n    var myLayout = (…)\n    \n    // lay out without resizing the container\n    myLayout.layout(container);\n    \n    // resize the container, then lay it out\n    container.bounds(myLayout.preferred());\n    myLayout.layout(container);\n\nA layout algorithm can be created by calling either the `grid` or `border` constructor in the `jLayout` namespace. Both constructors take an option object containing layout specific properties. Both layouts have the following properties in common:\n\n\u003cdl\u003e\n    \u003cdt\u003ehgap\u003c/dt\u003e\n    \u003cdd\u003eThe horizontal space between the laid out components. Should be a number in a coordinate space of your choice. Defaults to 0. Optional.\u003c/dd\u003e\n\n    \u003cdt\u003evgap\u003c/dt\u003e\n    \u003cdd\u003eThe vertical space between the laid out components. Should be a number in a coordinate space of your choice. Defaults to 0. Optional.\u003c/dd\u003e\n\u003c/dl\u003e\n\nThe other properties are specific to the layout algorithm and are discussed below.\n\n### Border layout\n\nThe border algorithm lays out components in five different regions. These regions are called `center`, `north`, `south`, `east` and `west`. The center component will be laid out in the center of the container, north on top of it, south beneath it and west and east on the left and right side respectively. The layout can only contain one of each region, but all are optional. Below is a visualization of a layout using all five regions.\n\n![](https://github.com/bramstein/jlayout/raw/master/assets/border.png)\n\nThe border algorithm takes an option object as parameter which can contain the following properties:\n\n\u003cdl\u003e\n    \u003cdt\u003ecenter, north, south east, west\u003c/dt\u003e\n    \u003cdd\u003eThe center, north, south, east or west component. All are optional.\u003c/dd\u003e\n\u003c/dl\u003e\n\nThe following example lays out a west, center and north component with a vertical space of 5 units between each component. There may be additional space between the components and the container if the container returns non-zero insets.\n\n    var borderLayout = jLayout.border({\n        west:   myWestComponent,\n        center: myCenterComponent,\n        north:  myNorthComponent,\n        vgap: 5\n    });\n    \n    borderLayout.layout(myContainer);\n\nIf a region is not specified or the component is not visible its space will be taken up by the other components.\n\n### Grid layout\n\nThe grid algorithm lays out the components in a grid, and resizes each component to the same size. The number of columns and rows can be specified by the user. Below is a visualization of a grid layout with four components in a 2x2 grid.\n\n![](https://github.com/bramstein/jlayout/raw/master/assets/grid.png)\n\nThe grid algorithm takes an option object as parameter which can contain the following properties:\n\n\u003cdl\u003e\n    \u003cdt\u003erows\u003c/dt\u003e\n    \u003cdd\u003eThe number of rows in the grid. Optional.\u003c/dd\u003e\n    \n    \u003cdt\u003ecolumns\u003c/dt\u003e\n    \u003cdd\u003eThe number of columns in the grid. Optional.\u003c/dd\u003e\n    \n    \u003cdt\u003eitems\u003c/dt\u003e\n    \u003cdd\u003eAn array containing the components to be laid out by the algorithm. Optional.\u003c/dd\u003e\n    \n    \u003cdt\u003efill\u003c/dt\u003e\n    \u003cdd\u003eThe direction in which the grid is filled in. Valid values are `horizontal` or `vertical` for filling in the grid left to right and top to bottom, or top to bottom and left to right respectivily. Optional.\u003c/dd\u003e\n\u003c/dl\u003e\n\nThe following example lays out four components in a 2x2 grid, without any spacing between the components.\n\n    var gridLayout = jLayout.grid({\n        rows: 2,\n        columns: 2,\n        items: [myComponent1, myComponent2, myComponent3, myComponent4]\n    });\n    \n    gridLayout.layout(myContainer);\n\nIf the number of rows is given, the number of columns is calculated automatically by taking the number of components into account. If the number of rows is not given (or set to zero), and the number of columns is given, the number of rows will be automatically calculated using the number of components. If neither is given, the number of rows is set equal to the number of components and the number of rows is set to zero.\n\n### Flex grid layout\n\nThe flex grid algorithm lays out the components in a grid with flexible row and columns sizes. The number of columns and rows can be specified by the user. Below is a visualization of a flex grid layout with six components in a 3x2 grid.\n\n![](https://github.com/bramstein/jlayout/raw/master/assets/flexgrid.png)\n\nThe flex grid algorithm takes an option object as parameter which can contain the following properties:\n\n\u003cdl\u003e\n    \u003cdt\u003erows\u003c/dt\u003e\n    \u003cdd\u003eThe number of rows in the flex grid. Optional.\u003c/dd\u003e\n    \n    \u003cdt\u003ecolumns\u003c/dt\u003e\n    \u003cdd\u003eThe number of columns in the flex grid. Optional.\u003c/dd\u003e\n    \n    \u003cdt\u003eitems\u003c/dt\u003e\n    \u003cdd\u003eAn array containing the components to be laid out by the algorithm. Optional.\u003c/dd\u003e\n\u003c/dl\u003e\n\nThe following example lays out six components in a 3x2 grid, without any spacing between the components.\n\n    var flexGridLayout = jLayout.flexGrid({\n        rows: 2,\n        columns: 2,\n        items: [myComponent1, myComponent2, myComponent3, \n                myComponent4, myComponent5, myComponent6]\n    });\n    \n    flexGridLayout.layout(myContainer);\n\nIf the number of rows is given, the number of columns is calculated automatically by taking the number of components into account. If the number of rows is not given (or set to zero,) and the number of columns is given, the number of rows will be automatically calculated using the number of components. If neither is given, the number of rows is set equal to the number of components and the number of rows is set to zero.\n\n### Flow layout\n\nThe flow algorithm lays out the components on a row. When the component does not fit on the current row it is moved to the next row. The alignment within the row can be user specified. Below is an example of a flow layout using five components with the alignment for each row set to left.\n\n![](https://github.com/bramstein/jlayout/raw/master/assets/flow.png)\n\nThe flow algorithm takes an option object as parameter which can contain the following properties:\n\n\u003cdl\u003e\n    \u003cdt\u003ealignment\u003c/dt\u003e\n    \u003cdd\u003eA string of either `center`, `left`, or `right`. Defaults to `left`.\u003c/dd\u003e\n    \n    \u003cdt\u003eitems\u003c/dt\u003e\n    \u003cdd\u003eAn array containing the components to be laid out by the algorithm. Optional.\u003c/dd\u003e\n\u003c/dl\u003e\n\nThe following example lays out five components using a center alignment, without any spacing between the components.\n\n    var flowLayout = jLayout.flow({\n        alignment: 'center',\n        items: [myComponent1, myComponent2, myComponent3, \n                myComponent4, myComponent5]\n    });\n    \n    flowLayout.layout(myContainer);\n\n### Horizontal and vertical layouts\n\nHorizontal and vertical layouts can be achieved by using a grid or a flexGrid layout with one row for horizontal layouts, and one column for vertical layouts. The choice of a grid layout or a flexGrid layout depends on whether or not you want the items in the grid to have uniform sizes (grid) or their natural sizes (flexGrid.) The following layout uses a flex grid so that all items are laid out in the horizontal direction while still allowing the individual items to take up their natural size (i.e. the second component is longer than the other two.)\n\n![](https://github.com/bramstein/jlayout/raw/master/assets/horizontal.png)\n\n    var horizontalLayout = jLayout.flexGrid({\n        rows: 1,\n        items: [myComponent1, myComponent2, myComponent3]\n    });\n\nYou can also lay out components vertically, by just changing the `rows` parameter to `columns` as shown in the next example.\n\n![](https://github.com/bramstein/jlayout/raw/master/assets/vertical.png)\n\n    var verticalLayout = jLayout.flexGrid({\n        columns: 1,\n        items: [myComponent1, myComponent2, myComponent3]\n    });\n\n## Questions, suggestions, or problems?\n\nPlease use the [jLayout Google Group](http://groups.google.com/group/jlayout/) for any questions, suggestions, ideas or problems you might have using the jLayout library or the jQuery plugin. Feedback is much appreciated.\n\n## License\n\nThis libary and the jQuery plugin are licensed under the\n[new BSD license](http://www.bramstein.com/licenses/BSD.txt). To summarize the license; the\nlibrary is completely free for commercial and non-commercial use and\nyou can do with it whatever you want, except claim it as your own\nwork.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbramstein%2Fjlayout","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbramstein%2Fjlayout","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbramstein%2Fjlayout/lists"}