{"id":20007564,"url":"https://github.com/kevm/bubbleo","last_synced_at":"2025-08-17T18:35:51.594Z","repository":{"id":223692167,"uuid":"759151166","full_name":"KevM/bubbleo","owner":"KevM","description":"BubbleO is a collection of components for the excellent terminal UI tool bubbletea. Includes: NavStack, Breadcrumbs, and Menu","archived":false,"fork":false,"pushed_at":"2024-05-09T14:53:20.000Z","size":3213,"stargazers_count":52,"open_issues_count":4,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-10T21:40:03.649Z","etag":null,"topics":["breadcrumbs","bubbletea","navigation-component"],"latest_commit_sha":null,"homepage":"","language":"Go","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/KevM.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":"2024-02-17T19:36:36.000Z","updated_at":"2025-06-13T01:45:21.000Z","dependencies_parsed_at":"2024-05-09T14:12:31.861Z","dependency_job_id":"ebe9f1d2-ad3e-4d86-b349-feb1aaeb35cf","html_url":"https://github.com/KevM/bubbleo","commit_stats":null,"previous_names":["kevm/bubbleo"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/KevM/bubbleo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KevM%2Fbubbleo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KevM%2Fbubbleo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KevM%2Fbubbleo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KevM%2Fbubbleo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KevM","download_url":"https://codeload.github.com/KevM/bubbleo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KevM%2Fbubbleo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270892136,"owners_count":24663540,"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-08-17T02:00:09.016Z","response_time":129,"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":["breadcrumbs","bubbletea","navigation-component"],"created_at":"2024-11-13T06:22:17.021Z","updated_at":"2025-08-17T18:35:51.514Z","avatar_url":"https://github.com/KevM.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BubbleO\n\nBubbleO is a collection of components for the excellent terminal UI tool [bubbletea](https://github.com/charmbracelet/bubbletea). \n\n[![Go Reference](https://pkg.go.dev/badge/github.com/kevm/bubbleo.svg)](https://pkg.go.dev/github.com/kevm/bubbleo)\n\n\n```bash\ngo get \"github.com/kevm/bubbleo\"\n```\n## [Navstack](https://github.com/KevM/bubbleo/blob/main/navstack/model.go)\n\nAdd support to your bubble tea application to easily transition between component models. The example below uses the [menu component](https://github.com/KevM/bubbleo/blob/main/menu/model.go) to let a user pick a color from a list of artist paintings.\n\n\u003cimg src=\"examples/deeper/demo.gif\" alt=\"Recording of the deeper example demo\"/\u003e\n\n```go \n    s := shell.New()\n    s.Navstack.Push(navstack.NavigationItem{Model: m, Title: \"Colors\"})\n    p := tea.NewProgram(s, tea.WithAltScreen())\n\n    _, err := p.Run()\n    if err != nil {\n        fmt.Println(\"Error running program:\", err)\n        os.Exit(1)\n    }\n```\n\nPush, well, pushes a new navigation item on the nav stack. The title is used for breadcrumbs (more later). The model at  the top of the navstack has it's Update and View funcs used effectively making it the presented component on the stack.\n\nPopping the stack will remove the topmost navigation item from the stack. \n\n### Navigation \n\nNavigation is accomplished by your components when they publish messages like `navstack.PushNavigation{}` or `navstack.PopNavigation{}`.\n\n#### Pushing a new component onto the stack\n\nThis example is from the included [menu component](https://github.com/KevM/bubbleo/blob/main/menu/model.go) which presents a list of choices. When a menu item is selected by pressing `enter` the choice's model is pushed onto the stack by publishing `navstack.PushNavigation`.\n\n```go \n    case tea.KeyEnter.String():\n        choice, ok := m.list.SelectedItem().(choiceItem)\n        if ok {\n            m.selected = \u0026choice.key\n            item := navstack.NavigationItem{Title: choice.title, Model: choice.key.Model}\n            cmd := utils.Cmdize(navstack.PushNavigation{Item: item})\n            return m, cmd\n        }\n```\n\nThere is no limit to the depth of the navigation stack. And the stack components may be dynamic based on your application and user needs.\n\n\u003e **Note:** [Cmdize](https://github.com/KevM/bubbleo/tree/main/utils/utils.go) simply wraps the given arg in a `tea.Cmd` (func that returns a `tea.Msg`)\n\n#### Popping the stack\n\nTo pop a component off the stack you might do the following in your bubbletea `Update` func. \n\n```go \n\tcase color.ColorSelected:\n\t\tpop := utils.Cmdize(navstack.PopNavigation{})\n\t\tcmd := utils.Cmdize(ArtistSelected{Name: m.Artist.Name, Color: msg.RGB})\n\t\treturn m, tea.Sequence(pop, cmd)\n```\n\nThe first cmd pops the current component off the stack while the second command is received by the previous component on the stack. This allows you to communicate the actions taken by the user up the nav stack. \n\nIf there are no items on the stack `tea.Quit` command is sent and the applicaiton exits.\n\n\u003e **Important:** In this example we are using `tea.Sequence` rather than the normal `tea.Batch` to ensure the messages are played in the correct order. This ensures the pop is played before the `ArtistSelected` which means the component below on the stack will get the message after the navstack is update. \n\n## Menu\n\nThe menu component wraps the excellent The [bubble/list component](https://github.com/charmbracelet/bubbletea/tree/master/examples/list-default) to let the user select from a menu of choices. Each choice is a model, title, and optional description which upon selection will take the user to this component's view. Menu expects to be used within a navigation stack. See the [simple](https://github.com/KevM/bubbleo/tree/main/examples/simple) and [deeper](https://github.com/KevM/bubbleo/tree/main/examples/deeper) examples for detailed usage.\n\n## Breadcrumb\n\nIt is handy to give the user a sense of place by presenting a [breadcrumb view](https://www.smashingmagazine.com/2022/04/breadcrumbs-ux-design/) showing them where they come from.\n\nCheckout the deeper example for usage of breadcrumbs.\n\n## Shell \n\nFinally the shell component emcapsulates the Breadcrumb and Navstack components allowing them to work together. See the [simple](https://github.com/KevM/bubbleo/tree/main/examples/simple) and [deeper](https://github.com/KevM/bubbleo/tree/main/examples/deeper) examples to see how it works.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkevm%2Fbubbleo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkevm%2Fbubbleo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkevm%2Fbubbleo/lists"}