{"id":2651,"url":"https://github.com/kazuhiro4949/PagingKit","last_synced_at":"2025-08-06T16:31:10.573Z","repository":{"id":37612080,"uuid":"96034920","full_name":"kazuhiro4949/PagingKit","owner":"kazuhiro4949","description":"PagingKit provides customizable menu UI. It has more flexible layout and design than the other libraries. ","archived":false,"fork":false,"pushed_at":"2022-08-08T23:47:02.000Z","size":1292,"stargazers_count":1404,"open_issues_count":8,"forks_count":123,"subscribers_count":20,"default_branch":"master","last_synced_at":"2024-12-07T02:09:02.843Z","etag":null,"topics":["ios","pageviewcontroller","paging","segmentcontrol","swift","uicollectionview","uicollectionviewlayout","uikit","uitableview"],"latest_commit_sha":null,"homepage":"","language":"Swift","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/kazuhiro4949.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-07-02T16:16:40.000Z","updated_at":"2024-11-26T11:35:07.000Z","dependencies_parsed_at":"2022-07-14T21:46:50.460Z","dependency_job_id":null,"html_url":"https://github.com/kazuhiro4949/PagingKit","commit_stats":null,"previous_names":[],"tags_count":65,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kazuhiro4949%2FPagingKit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kazuhiro4949%2FPagingKit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kazuhiro4949%2FPagingKit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kazuhiro4949%2FPagingKit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kazuhiro4949","download_url":"https://codeload.github.com/kazuhiro4949/PagingKit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228923694,"owners_count":17992567,"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":["ios","pageviewcontroller","paging","segmentcontrol","swift","uicollectionview","uicollectionviewlayout","uikit","uitableview"],"created_at":"2024-01-05T20:16:19.280Z","updated_at":"2024-12-09T16:31:02.493Z","avatar_url":"https://github.com/kazuhiro4949.png","language":"Swift","readme":"![img](https://user-images.githubusercontent.com/18320004/31583441-eb6ff894-b1d6-11e7-943a-675d6460919a.png)\n\n\n[![Platform](https://img.shields.io/cocoapods/p/PagingKit.svg?style=flat)](http://cocoapods.org/pods/PagingKit)\n![Swift 5.1](https://img.shields.io/badge/Swift-5.1-orange.svg)\n[![License](https://img.shields.io/cocoapods/l/PagingKit.svg?style=flat)](http://cocoapods.org/pods/PagingKit)\n[![Version](https://img.shields.io/cocoapods/v/PagingKit.svg?style=flat)](http://cocoapods.org/pods/PagingKit)\n[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)\n[![Swift Package Manager compatible](https://img.shields.io/badge/Swift_Package_Manager-compatible-4BC51D.svg?style=flat)](https://swift.org/package-manager/)\n\nPagingKit provides customizable menu \u0026 content UI. It has more flexible layout and design than the other libraries.\n\n# What's this?\nThere are many libraries providing \"Paging UI\" which have menu and content area.\nThey are convenient but not customizable because your app has to be made compatible with the libraries' layout and view components.\nWhen a UI desgin in your app doesn't fit the libraries, you need to fork them or find another one. \n\nPagingKit has more flexible layout and design than the other libraries.\nYou can construct \"Menu\" and \"Content\" UI, and they work together. That's all features this library provides.\nYou can fit any design to your apps as you like.\n\n![paging_sample](https://user-images.githubusercontent.com/18320004/31575892-35860ae2-b12b-11e7-9525-1825c69b094f.gif)\n\n## Customized layout \nYou can align views as you like.\n\n| changing position | placing a view between content and menu | added floating button on right-side | on navigation bar | \n|:------------:|:------------:|:------------:|:------------:|\n| ![sample_5](https://user-images.githubusercontent.com/18320004/31857631-08683bf4-b71e-11e7-83c4-ee4e942b5ea1.gif) | ![sample_4](https://user-images.githubusercontent.com/18320004/31857630-075948c0-b71e-11e7-9ea7-3d490c733b7f.gif) | ![sample6](https://user-images.githubusercontent.com/18320004/33793722-f9806f46-dcff-11e7-9909-a9f87e9ef4a0.gif) | \u003cimg width=\"320\" alt=\"2018-12-04 10 00 51\" src=\"https://user-images.githubusercontent.com/18320004/49411286-aa187d00-f7ab-11e8-9672-094e10853778.png\"\u003e |\n\n## Customized menu design\nYou can customize menu as you like.\n\n| tag like menu | text highlighted menu | underscore menu | App Store app like indicator | \n|:------------:|:------------:|:------------:|:------------:|\n| ![sample_3](https://user-images.githubusercontent.com/18320004/31857535-d8b6965a-b71b-11e7-928d-46375c2cfb7b.gif) | \u003cimg src=\"https://user-images.githubusercontent.com/18320004/49323491-a42e5c00-f55f-11e8-9690-295acc2c3341.gif\" width=280\u003e  | ![sample_1](https://user-images.githubusercontent.com/18320004/31857533-d69720ba-b71b-11e7-9401-534596dbb76d.gif) | ![indicator](https://user-images.githubusercontent.com/18320004/32141748-3e6c4fc6-bccb-11e7-8a6a-0286982f938b.gif) |\n\nI'm looking for a pull request of your custom menu design :)\n\n# Feature\n- [x] easy to construct Paging UI\n- [x] customizable layout and design\n- [x] UIKit like API\n- [x] Supporting iPhone, iPad and iPhone X\n\n# Requirements\n+ iOS 9.0+\n+ Xcode 11.0+\n+ Swift 5.1\n\n# Installation\n\n## Swift Package Manager\nopen Swift Packages (which is next to Build Settings). You can add and remove packages from this tab.\n\nSee [Adding Package Dependencies to Your App](https://developer.apple.com/documentation/xcode/adding_package_dependencies_to_your_app)\n\n## CocoaPods\n+ Install CocoaPods\n```\n\u003e gem install cocoapods\n\u003e pod setup\n```\n+ Create Podfile\n```\n\u003e pod init\n```\n+ Edit Podfile\n```ruby\ntarget 'YourProject' do\n  use_frameworks!\n\n  pod \"PagingKit\" # add\n\n  target 'YourProject' do\n    inherit! :search_paths\n  end\n\n  target 'YourProject' do\n    inherit! :search_paths\n  end\n\nend\n```\n\n+ Install\n\n```\n\u003e pod install\n```\nopen .xcworkspace\n\n## Carthage\n+ Install Carthage from Homebrew\n```\n\u003e ruby -e \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)\"\n\u003e brew update\n\u003e brew install carthage\n```\n+ Move your project dir and create Cartfile\n```\n\u003e touch Cartfile\n```\n+ add the following line to Cartfile\n```\ngithub \"kazuhiro4949/PagingKit\"\n```\n+ Create framework\n```\n\u003e carthage update --platform iOS\n```\n\n+ In Xcode, move to \"Genera \u003e Build Phase \u003e Linked Frameworks and Library\"\n+ Add the framework to your project\n+ Add a new run script and put the following code\n```\n/usr/local/bin/carthage copy-frameworks\n```\n+ Click \"+\" at Input file and Add the framework path\n```\n$(SRCROOT)/Carthage/Build/iOS/PagingKit.framework\n```\n+ Write Import statement on your source file\n```\nimport PagingKit\n```\n\n# Getting Started\n\nThere are some samples in this library.\n\nhttps://github.com/kazuhiro4949/PagingKit/tree/master/iOS%20Sample/iOS%20Sample\n\nYou can fit PagingKit into your project as the samples do. Check out this repository and open the workspace.\n\nPagingKit has two essential classes.\n- PagingMenuViewController\n- PagingContentViewController\n\nPagingMenuViewController provides interactive menu for each content. PagingContentViewController provides the contents on a scrollview.\n\nIf you make a new project which contains PagingKit, follow the steps.\n\n1. Add PagingMenuViewController \u0026 PagingContentViewController\n2. Assign them to properties\n3. Create menu UI\n4. display data\n5. Synchronize Menu and Content view controllers\n\n## 1. Add PagingMenuViewController \u0026 PagingContentViewController\nFirst, add PagingMenuViewController \u0026 PagingContentViewController on container view with Stroyboard.\n\n### 1. Put container views on Storyboard\nPut container views on stroyboard for each the view controllers.\n\n\u003cimg width=\"1417\" alt=\"2017-08-25 16 33 51\" src=\"https://user-images.githubusercontent.com/18320004/29704102-491f0e72-89b3-11e7-9d69-7988969ef18e.png\"\u003e\n\n### 2. Change class names\n\ninput PagingMenuViewController on custom class setting.\n\u003cimg width=\"1418\" alt=\"2017-08-25 16 36 36\" src=\"https://user-images.githubusercontent.com/18320004/29704183-a59ab390-89b3-11e7-9e72-e98ee1e9abc0.png\"\u003e\n\ninput PagingContentViewController on custom class setting.\n\n\u003cimg width=\"1415\" alt=\"2017-08-25 16 36 54\" src=\"https://user-images.githubusercontent.com/18320004/29704184-a669f344-89b3-11e7-91b6-90669fa2190f.png\"\u003e\n\n## 2. Assign them to properties\n\nAssign them on code of the container view controller.\n\n### 1. Declare properties for the view controllers \nDeclare properties in container view controller.\n```swift\nclass ViewController: UIViewController {\n    \n    var menuViewController: PagingMenuViewController!\n    var contentViewController: PagingContentViewController!\n```\n\n### 2. override prepare(segue:sender:) and assign the view controllers\nAssigin view controllers to each the property on ```prepare(segue:sender:)```.\n\n```swift\n    override func prepare(for segue: UIStoryboardSegue, sender: Any?) {\n        if let vc = segue.destination as? PagingMenuViewController {\n            menuViewController = vc\n        } else if let vc = segue.destination as? PagingContentViewController {\n            contentViewController = vc\n        }\n    }\n```\n\n### 3. Build App\nChange menu color.\n\u003cimg width=\"1097\" alt=\"2017-08-25 17 47 58\" src=\"https://user-images.githubusercontent.com/18320004/29706662-922732ac-89bd-11e7-8969-bd6fbe394a8a.png\"\u003e\n\nBuild and check the current state.\n\n\u003cimg width=\"487\" alt=\"2017-08-25 17 47 29\" src=\"https://user-images.githubusercontent.com/18320004/29706651-84749258-89bd-11e7-9239-6919a0175a17.png\"\u003e\n\nIt shows a container view controller that has PagingMenuViewController and PagingContentViewController.\n\n## 3. Create menu UI\n\nNext, you needs to prepare the menu elements.\n\n### 1. Inherite PagingMenuViewCell and create custom cell\n\nPagingKit has PagingMenuViewCell. PagingMenuViewController uses it to construct each menu element.\n\n```swift\nimport UIKit\nimport PagingKit\n\nclass MenuCell: PagingMenuViewCell {\n    @IBOutlet weak var titleLabel: UILabel!\n}\n```\n\n\u003cimg width=\"1414\" alt=\"2017-08-25 16 56 56\" src=\"https://user-images.githubusercontent.com/18320004/29704850-7b877cd4-89b6-11e7-98c9-48eb94646291.png\"\u003e\n\n\n### 2. Inherite PagingFocusView and create custom view\n\nPagingKit has PagingFocusView. PagingMenuViewController uses it to point the current focusted menu.\n\n\u003cimg width=\"1420\" alt=\"2017-08-25 16 59 07\" src=\"https://user-images.githubusercontent.com/18320004/29704919-bd3d8f06-89b6-11e7-88dc-c8546979dbde.png\"\u003e\n\n\n### 3. register the above views to PagingMenuViewController\n\n```swift\nclass ViewController: UIViewController {\n    \n    var menuViewController: PagingMenuViewController!\n    var contentViewController: PagingContentViewController!\n\n    override func viewDidLoad() {\n        super.viewDidLoad()\n        \n        menuViewController.register(nib: UINib(nibName: \"MenuCell\", bundle: nil), forCellWithReuseIdentifier: \"MenuCell\")\n        menuViewController.registerFocusView(nib: UINib(nibName: \"FocusView\", bundle: nil))\n    }\n```\n\n## 4. display data\n\nThen, implement the data sources to display contents. They are a similar to UITableViewDataSource.\n\n### 1. prepare data\n\n```swift\nclass ViewController: UIViewController {\n    static var viewController: (UIColor) -\u003e UIViewController = { (color) in\n       let vc = UIViewController()\n        vc.view.backgroundColor = color\n        return vc\n    }\n    \n    var dataSource = [(menuTitle: \"test1\", vc: viewController(.red)), (menuTitle: \"test2\", vc: viewController(.blue)), (menuTitle: \"test3\", vc: viewController(.yellow))]\n```\n\n### 2. set menu data source\n\nReturn number of menus, menu widthes and PagingMenuViewCell objects.\n\n```swift\n    override func prepare(for segue: UIStoryboardSegue, sender: Any?) {\n        if let vc = segue.destination as? PagingMenuViewController {\n            menuViewController = vc\n            menuViewController.dataSource = self // \u003c- set menu data source\n        } else if let vc = segue.destination as? PagingContentViewController {\n            contentViewController = vc\n        }\n    }\n}\n\nextension ViewController: PagingMenuViewControllerDataSource {\n    func numberOfItemsForMenuViewController(viewController: PagingMenuViewController) -\u003e Int {\n        return dataSource.count\n    }\n    \n    func menuViewController(viewController: PagingMenuViewController, widthForItemAt index: Int) -\u003e CGFloat {\n        return 100\n    }\n    \n    func menuViewController(viewController: PagingMenuViewController, cellForItemAt index: Int) -\u003e PagingMenuViewCell {\n        let cell = viewController.dequeueReusableCell(withReuseIdentifier: \"MenuCell\", for: index) as! MenuCell\n        cell.titleLabel.text = dataSource[index].menuTitle\n        return cell\n    }\n}\n```\n\n### 3. configure content data source\n\nReturn the number of contents and view controllers.\n\n```swift\n    override func prepare(for segue: UIStoryboardSegue, sender: Any?) {\n        if let vc = segue.destination as? PagingMenuViewController {\n            menuViewController = vc\n            menuViewController.dataSource = self\n        } else if let vc = segue.destination as? PagingContentViewController {\n            contentViewController = vc\n            contentViewController.dataSource = self // \u003c- set content data source\n        }\n    }\n}\n\nextension ViewController: PagingContentViewControllerDataSource {\n    func numberOfItemsForContentViewController(viewController: PagingContentViewController) -\u003e Int {\n        return dataSource.count\n    }\n    \n    func contentViewController(viewController: PagingContentViewController, viewControllerAt index: Int) -\u003e UIViewController {\n        return dataSource[index].vc\n    }\n}\n```\n\n### 4. load UI\n\nCall reloadData() methods with starting point.\n\n```swift\n    override func viewDidLoad() {\n        super.viewDidLoad()\n        //...\n        //...\n        menuViewController.reloadData()\n        contentViewController.reloadData()\n    }\n```\n\nBuild and display data source.\n\n\u003cimg width=\"487\" alt=\"2017-08-25 17 54 30\" src=\"https://user-images.githubusercontent.com/18320004/29706950-7e1b41a8-89be-11e7-8bb2-fc90afbe11f7.png\"\u003e\n\n## 5. Synchronize Menu and Content view controllers\n\nLast, synchronize user interactions between Menu and Content.\n\n### 1. set menu delegate\n\n```swift\n    override func prepare(for segue: UIStoryboardSegue, sender: Any?) {\n        if let vc = segue.destination as? PagingMenuViewController {\n            menuViewController = vc\n            menuViewController.dataSource = self\n            menuViewController.delegate = self // \u003c- set menu delegate\n        } else if let vc = segue.destination as? PagingContentViewController {\n            contentViewController = vc\n            contentViewController.dataSource = self\n        }\n    }\n}\n```\n\nImplement menu delegate to handle the event. It is a similar to UITableViewDelegate. You need to implement scroll method of PagingContentViewController in the delegate method.\n\n```swift\n\nextension ViewController: PagingMenuViewControllerDelegate {\n    func menuViewController(viewController: PagingMenuViewController, didSelect page: Int, previousPage: Int) {\n        contentViewController.scroll(to: page, animated: true)\n    }\n}\n```\n\n### 2. set content delegate\n\n```swift\n    override func prepare(for segue: UIStoryboardSegue, sender: Any?) {\n        if let vc = segue.destination as? PagingMenuViewController {\n            menuViewController = vc\n            menuViewController.dataSource = self\n            menuViewController.delegate = self\n        } else if let vc = segue.destination as? PagingContentViewController {\n            contentViewController = vc\n            contentViewController.dataSource = self\n            contentViewController.delegate = self // \u003c- set content delegate\n        }\n    }\n}\n```\n\nImplement content delegate to handle the event. It is similar to UIScrollViewDelegate. You need to implement the scroll event of PagingMenuViewController. \"percent\" is distance from \"index\" argument to the right-side page index.\n\n```swift\nextension ViewController: PagingContentViewControllerDelegate {\n    func contentViewController(viewController: PagingContentViewController, didManualScrollOn index: Int, percent: CGFloat) {\n        menuViewController.scroll(index: index, percent: percent, animated: false)\n    }\n}\n```\n\nThat's it.\n\n# Tips\n- [Build-in UI components](https://github.com/kazuhiro4949/PagingKit/blob/master/Documentation/Tips.md#build-in-ui-components)\n- [Focused Cell Style](https://github.com/kazuhiro4949/PagingKit/blob/master/Documentation/Tips.md#focused-cell-style)\n- [Cell Alignment](https://github.com/kazuhiro4949/PagingKit/blob/master/Documentation/Tips.md#cell-alignment)\n- [Underline to have the same width as each title label](https://github.com/kazuhiro4949/PagingKit/blob/master/Documentation/Tips.md#underline-to-have-the-same-width-as-each-title-label)\n- [Controlling PagingContentViewController's scroll](https://github.com/kazuhiro4949/PagingKit/blob/master/Documentation/Tips.md#controlling-pagingcontentviewcontrollers-scroll)\n- [Initializing without Storyboard](https://github.com/kazuhiro4949/PagingKit/blob/master/Documentation/Tips.md#initializing-without-storyboard)\n- [Put menu on UINavigationBar](https://github.com/kazuhiro4949/PagingKit/blob/master/Documentation/Tips.md#put-menu-on-uinavigationbar)\n- [Animating alongside PagingMenuFocusView](https://github.com/kazuhiro4949/PagingKit/blob/master/Documentation/Tips.md#animating-alongside-pagingmenufocusview)\n- [RTL Support](https://github.com/kazuhiro4949/PagingKit/blob/master/Documentation/Tips.md#rtl-support)\n- [Code Snippets](https://github.com/kazuhiro4949/PagingKit/blob/master/Documentation/Tips.md#code-snippets)\n\n# Class Design\nThere are some design policy in this library.\n\n- The behavior needs to be specified by the library.\n- The layout should be left to developers.\n- Arrangement of the internal components must be left to developers.\n\nBecause of that, PagingKit has responsiblity for the behavior. But it doesn't specify a structure of the components.\nPagingKit favours composition over inheritance. This figure describes overview of the class diagram.\n\n\u003cimg src=\"https://user-images.githubusercontent.com/18320004/38431789-628100e8-3a00-11e8-8ae2-30cd6122ec9a.png\" width=\"500\" /\u003e\n\n# Work with RxSwift\n\nPagingKit goes well with RxSwift.\n\nhttps://github.com/kazuhiro4949/RxPagingKit\n\n```swift\n    let items = PublishSubject\u003c[(menu: String, width: CGFloat, content: UIViewController)]\u003e()\n\n    override func viewDidLoad() {\n        super.viewDidLoad()\n        \n        menuViewController?.register(type: TitleLabelMenuViewCell.self, forCellWithReuseIdentifier: \"identifier\")\n        menuViewController?.registerFocusView(view: UnderlineFocusView())\n        \n        // PagingMenuViewControllerDataSource\n        items.asObserver()\n            .map { items in items.map({ ($0.menu, $0.width) }) }\n            .bind(to: menuViewController.rx.items(\n                cellIdentifier: \"identifier\",\n                cellType: TitleLabelMenuViewCell.self)\n            ) { _, model, cell in\n                cell.titleLabel.text = model\n            }\n            .disposed(by: disposeBug)\n        \n        // PagingContentViewControllerDataSource\n        items.asObserver()\n            .map { items in items.map({ $0.content }) }\n            .bind(to: contentViewController.rx.viewControllers())\n            .disposed(by: disposeBug)\n        \n        // PagingMenuViewControllerDelegate\n        menuViewController.rx.itemSelected.asObservable().subscribe(onNext: { [weak self] (page, prev) in\n            self?.contentViewController.scroll(to: page, animated: true)\n        }).disposed(by: disposeBug)\n        \n        // PagingContentViewControllerDelegate\n        contentViewController.rx.didManualScroll.asObservable().subscribe(onNext: { [weak self] (index, percent) in\n            self?.menuViewController.scroll(index: index, percent: percent, animated: false)\n        }).disposed(by: disposeBug)\n    }\n```\n\n\n\n# License\n\nCopyright (c) 2017 Kazuhiro Hayashi\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","funding_links":[],"categories":["UI","Libs","PageControl","Swift","UI [🔝](#readme)"],"sub_categories":["Menu","UI","Other free courses"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkazuhiro4949%2FPagingKit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkazuhiro4949%2FPagingKit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkazuhiro4949%2FPagingKit/lists"}