{"id":2966,"url":"https://github.com/algolia/instantsearch-ios","last_synced_at":"2025-04-14T01:04:20.814Z","repository":{"id":39719184,"uuid":"86334597","full_name":"algolia/instantsearch-ios","owner":"algolia","description":"⚡️ A library of widgets and helpers to build instant-search applications on iOS.","archived":false,"fork":false,"pushed_at":"2025-02-20T14:53:34.000Z","size":98825,"stargazers_count":602,"open_issues_count":25,"forks_count":60,"subscribers_count":73,"default_branch":"master","last_synced_at":"2025-04-06T21:11:57.371Z","etag":null,"topics":["algolia","custom-widgets","faceted-search","geo-search","instant-search","interface-builder","ios","ios-library","open-source","search","search-engine","search-interface","search-synonyms","swift","widgets"],"latest_commit_sha":null,"homepage":"https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/ios/","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/algolia.png","metadata":{"files":{"readme":"Readme.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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":"2017-03-27T12:48:21.000Z","updated_at":"2025-04-06T16:28:05.000Z","dependencies_parsed_at":"2022-07-14T23:00:36.745Z","dependency_job_id":"62ed3090-1a8f-499d-b706-9317fbedff3f","html_url":"https://github.com/algolia/instantsearch-ios","commit_stats":{"total_commits":909,"total_committers":24,"mean_commits":37.875,"dds":"0.49504950495049505","last_synced_commit":"1430cf9b998c04682116b5e134f4181a1f800bf6"},"previous_names":[],"tags_count":77,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algolia%2Finstantsearch-ios","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algolia%2Finstantsearch-ios/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algolia%2Finstantsearch-ios/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algolia%2Finstantsearch-ios/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/algolia","download_url":"https://codeload.github.com/algolia/instantsearch-ios/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248804803,"owners_count":21164134,"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":["algolia","custom-widgets","faceted-search","geo-search","instant-search","interface-builder","ios","ios-library","open-source","search","search-engine","search-interface","search-synonyms","swift","widgets"],"created_at":"2024-01-05T20:16:27.627Z","updated_at":"2025-04-14T01:04:20.769Z","avatar_url":"https://github.com/algolia.png","language":"Swift","funding_links":[],"categories":["UI","Libs","Swift","UI [🔝](#readme)"],"sub_categories":["TextField \u0026 TextView","UI","Other free courses"],"readme":"![InstantSearch iOS](./Resources/instantsearch-banner.png)\n\n[![Pod Version](http://img.shields.io/cocoapods/v/InstantSearch.svg?style=flat)](https://github.com/algolia/instantsearch-ios/)\n[![Pod Platform](http://img.shields.io/cocoapods/p/InstantSearch.svg?style=flat)](https://github.com/algolia/instantsearch-ios/)\n[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-brightgreen.svg)](https://github.com/algolia/instantsearch-ios/)\n[![SwiftPM compatible](https://img.shields.io/badge/SwiftPM-compatible-brightgreen.svg)](https://swift.org/package-manager/)\n[![Mac Catalyst compatible](https://img.shields.io/badge/Catalyst-compatible-brightgreen.svg)](https://developer.apple.com/documentation/xcode/creating_a_mac_version_of_your_ipad_app/)\n[![Licence](http://img.shields.io/cocoapods/l/InstantSearch.svg?style=flat)](https://opensource.org/licenses/Apache-2.0)\n\nBy [Algolia](http://algolia.com).\n\nInstantSearch family: **InstantSearch iOS** | [InstantSearch Android][instantsearch-android-github] | [React InstantSearch][react-instantsearch-github] | [InstantSearch.js][instantsearch-js-github] | [Angular InstantSearch][instantsearch-angular-github] | [Vue InstantSearch][instantsearch-vue-github].\n\n**InstantSearch iOS** is a framework providing components and helpers to help you build the best instant-search experience on iOS with Algolia. It is built on top of Algolia's [Swift API Client](https://github.com/algolia/algoliasearch-client-swift) library to provide you a high-level solution to quickly build various search interfaces.\n\n## Structure\n\n **InstantSearch iOS** consists of three products\n - *[InstantSearch Insights](./Sources/InstantSearchInsights/README.md)* – library that allows developers to capture search-related events\n - *InstantSearch Core* – the business logic modules of InstantSearch\n - *InstantSearch* – the complete InstantSearch toolset including UIKit components\n - *InstantSearch SwiftUI* – the set of SwiftUI data models and views to use on top of Core components\n\n## Examples\n\nYou can see InstantSearch iOS in action in the [Examples project](/Examples). It contains search components ans experiences built with InstantSearch and written in Swift.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"./Resources/instant-results.gif\" width=\"300\"/\u003e\n\u003c/p\u003e\n\n\n## Installation\n\n### Swift Package Manager\n\nThe Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system to automate the process of downloading, compiling, and linking dependencies. \nSince the release of Swift 5 and Xcode 11, SPM is compatible with the iOS, macOS and tvOS build systems for creating apps. \n\nTo use SwiftPM, you should use Xcode 11 to open your project. Click `File` -\u003e `Swift Packages` -\u003e `Add Package Dependency`, enter [InstantSearch repo's URL](https://github.com/algolia/instantsearch-ios).\nNext, select the products you consider to use in your project from the provided list.\n\nIf you're a framework author and use InstantSearch as a dependency, update your `Package.swift` file:\n\n```swift\nlet package = Package(\n    // 7.26.0 ..\u003c 8.0.0\n    dependencies: [\n        .package(url: \"https://github.com/algolia/instantsearch-ios\", from: \"7.26.0\")\n    ],\n    // ...\n)\n```\n\n### CocoaPods\n\n[CocoaPods](https://cocoapods.org/) is a dependency manager for Cocoa projects.\n\nTo install InstantSearch, simply add the following line to your Podfile:\n\n```ruby\npod 'InstantSearch', '~\u003e 7.26'\n# pod 'InstantSearch/Insights' for access to Insights library only\n# pod 'InstantSearch/Core' for access business logic without UIKit components\n# pod 'InstantSearch/SwiftUI' for access to SwiftUI components\n```\n\nThen, run the following command:\n\n```bash\n$ pod update\n```\n\n### Carthage\n\n[Carthage](https://github.com/Carthage/Carthage) is a simple, decentralized dependency manager for Cocoa.\n\n- To install InstantSearch, simply add the following line to your Cartfile:\n```ruby\ngithub \"algolia/instantsearch-ios\" ~\u003e 7.26\n```\n\n- Launch the following commands from the project directory\n ```shell\n carthage update\n ./Carthage/Checkouts/instant-search-ios/carthage-prebuild\n carthage build\n ```\n\n \u003e NOTE: At this time, Carthage does not provide a way to build only specific repository subcomponents (or equivalent of CocoaPods's subspecs). All components and their dependencies will be built with the above command. However, you don't need to copy frameworks you aren't using into your project. For instance, if you aren't using UI components from `InstantSearch`, feel free to delete that framework from the Carthage Build directory after `carthage update` completes keeping only `InstantSearchCore`. If you only need event-tracking functionalities, delete all but `InstantSearchInsights` framework.\n \n If this is your first time using Carthage in the project, you'll need to go through some additional steps as explained [over at Carthage](https://github.com/Carthage/Carthage#adding-frameworks-to-an-application).\n \n\n## Documentation\n\n**You can start with the [Getting Started Guide](https://www.algolia.com/doc/guides/building-search-ui/getting-started/ios/).**\n\nLearn more about instantSearch iOS in the [dedicated documentation website](https://www.algolia.com/doc/api-reference/widgets/ios/).\n\n## Basic Usage\nIn your `ViewController.swift`:\n\n```swift\nimport InstantSearch\n\nstruct Item: Codable {\n  let name: String\n}\n\nclass SearchResultsViewController: UITableViewController, HitsController {\n  \n  var hitsSource: HitsInteractor\u003cItem\u003e?\n    \n  override func viewDidLoad() {\n    super.viewDidLoad()\n    tableView.register(UITableViewCell.self, forCellReuseIdentifier: \"cell\")\n  }\n      \n  override func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -\u003e Int {\n    hitsSource?.numberOfHits() ?? 0\n  }\n  \n  override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -\u003e UITableViewCell {\n    let cell = tableView.dequeueReusableCell(withIdentifier: \"cell\", for: indexPath)\n    cell.textLabel?.text = hitsSource?.hit(atIndex: indexPath.row)?.name\n    return cell\n  }\n  \n  override func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {\n    if let _ = hitsSource?.hit(atIndex: indexPath.row) {\n      // Handle hit selection\n    }\n  }\n  \n}\n\nclass ViewController: UIViewController {\n      \n  lazy var searchController = UISearchController(searchResultsController: hitsViewController)\n  let hitsViewController = SearchResultsViewController()\n\n  let searcher = HitsSearcher(appID: \"latency\",\n                              apiKey: \"1f6fd3a6fb973cb08419fe7d288fa4db\",\n                              indexName: \"bestbuy\")\n  lazy var searchConnector = SearchConnector\u003cItem\u003e(searcher: searcher,\n                                                    searchController: searchController,\n                                                    hitsInteractor: .init(),\n                                                    hitsController: hitsViewController)\n  \n  override func viewDidLoad() {\n    super.viewDidLoad()\n    searchConnector.connect()\n    searcher.search()\n    setupUI()\n  }\n  \n  override func viewDidAppear(_ animated: Bool) {\n    super.viewDidAppear(animated)\n    searchController.isActive = true\n  }\n  \n  func setupUI() {\n    view.backgroundColor = .white\n    navigationItem.searchController = searchController\n    searchController.hidesNavigationBarDuringPresentation = false\n    searchController.showsSearchResultsController = true\n    searchController.automaticallyShowsCancelButton = false\n  }\n      \n}\n```\n\nYou can now build and run your application to see the basic search experience in action. \nYou should see that the results are changing on each key stroke.\n\nTo get a more meaningful search experience, please follow the [Getting Started Guide](https://www.algolia.com/doc/guides/building-search-ui/getting-started/ios/).\nIf you build a SwiftUI application, please check out the Getting [Started with SwiftUI guide](https://www.algolia.com/doc/guides/building-search-ui/getting-started/how-to/declarative/ios/)\n\nIf you only require business logic modules in your project and use `InstantSearchCore` framework, add `import InstantSearchCore` to your source files. \n\n## Logs\n\nThere are 7 levels of logs severity produced by the library. \nThe default severity level is `.info`. \nYou can configure the logging level as follows: \n```\nLogs.logSeverityLevel = .debug\n```  \n\n\n## Telemetry\n\nInstantSearch iOS collects data points at runtime. This helps the InstantSearch team improve and prioritize future development.\n\nHere's an exhaustive list of the collected data:\n\n- InstantSearch version\n- The name of the instantiated InstantSearch components, for example, `HitsSearcher`, `FilterState`\n- The name of the components with custom parameters (overridden defaults). InstantSearch doesn't collect the values of those parameters. For example, the default of the `facets` value in `FacetListInteractor` is an empty list. If you instantiate it with a list of facets, then the telemetry tracks that the `facets` parameter received a custom value, but not the value itself.\n\n InstantSearch doesn't collect any sensitive or personal data. However, you can still opt out of the telemetry collection with the following code:\n ```swift\n InstantSearchTelemetry.shared.isEnabled = false\n ```\n\n## Getting Help\n\n- **Need help**? Ask a question to the [Algolia Community](https://discourse.algolia.com/) or on [Stack Overflow](http://stackoverflow.com/questions/tagged/algolia).\n- **Encountering an issue?** Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/guides/building-search-ui/troubleshooting/faq/ios/) where you will find answers for the most common issues and gotchas with the framework.\n- **Found a bug?** You can open a [GitHub issue](https://github.com/algolia/algoliasearch-client-swift/issues).\n- **Questions about Algolia?** You can search our [FAQ in our website](https://www.algolia.com/doc/faq/).\n\n\n## Getting involved\n\n* If you **want to contribute** please feel free to **submit pull requests**.\n* If you **have a feature request** please **open an issue**.\n* If you use **InstantSearch** in your app, we would love to hear about it! Drop us a line on [discourse](https://discourse.algolia.com/) or [twitter](https://twitter.com/algolia).\n\n# License\n\nInstantSearch iOS is [Apache 2.0 licensed](LICENSE.md).\n\n[react-instantsearch-github]: https://github.com/algolia/react-instantsearch/\n[instantsearch-android-github]: https://github.com/algolia/instantsearch-android\n[instantsearch-js-github]: https://github.com/algolia/instantsearch.js\n[instantsearch-vue-github]: https://github.com/algolia/vue-instantsearch\n[instantsearch-angular-github]: https://github.com/algolia/angular-instantsearch\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falgolia%2Finstantsearch-ios","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falgolia%2Finstantsearch-ios","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falgolia%2Finstantsearch-ios/lists"}