View Source LivePalette (LivePalette v0.1.1)

LivePalette is a component for Phoenix.LiveView that allows the user to implement a command palette, reminiscent of the VSCode and Sublime Command Palettes, the macOS Spotlight and Alfred, and Linear's Command-K Command Bar.

Summary

Functions

The live palette component itself.

Functions

The live palette component itself.

Attributes

  • id (:string) (required) - The component ID. The underlying implementation of the LivePalette component is a LiveComponent, which requires a component ID.

  • actions (:list) (required) - The list of possible actions available to this palette. Actions passed in to this list must implement the LivePalette.Actionable protocol.

  • show_on_initial_render (:boolean) - Whether or not to show the palette on the initial render. The LivePalette is a LiveComponent, so this property once set is then owned by the component itself, meaning that it should only be set once (on render), and subsequently left to the component to decide when to show or hide. This is by default set to false, however, in cases such as a reconnect or a refresh, when one might want to ensure that the user receives the same view that they had previously, this can be set to true to show it on the initial render.

    Defaults to false.

  • key (:string) - The key that should trigger showing the palette. This defaults to K. Defaults to "K".

  • require_metakey (:boolean) - Whether or not the key should be pressed with the meta key. An explanation of how to enable the metadata that includes whether the meta key was pressed can be found on the Phoenix LiveView Key Events documentation. If set to true, this will expect that you have enabled this metadata on your socket, and it will only match and toggle the palette when both the given key and the meta key are pressed together.

    Defaults to false.

  • match_threshold (:float) - The minimum threshold that we need in order to determine if the action is a match to a specific search term. The action's title and subtitle will be checked against the search term as the user types it, and the actions will be sorted by score.

    The value must be a float between 0.0 and 1.0. The default threshold to 0.3.

    Defaults to 0.3.

  • maximum_results (:integer) - The maximum results to show when displaying the results of actions in the list. The default maximum is 10.

    Defaults to 10.

  • metakey_param (:string) - The param on the key event that the meta key value appears in. When setting require_metakey to true, this value is used to get the parameter from the params sent in the event. By default, this is set to "metaKey", which is taken from the example provided in the Phoenix LiveView Key Events documentation.

    If you have a different parameter name, you must update this attribute in order to ensure that it is properly matched.

    Defaults to "metaKey".

  • placeholder (:string) - The placeholder that will be added to the palette's input. This defaults to "Enter your command".

    Defaults to "Enter your command".

  • show_all_results_on_empty_input (:boolean) - Whether or not to show all of the results when the input is empty. This is set to false by default, however, when set to true, when the input is empty we will create a full list of all of the palettes actions and show them in a scrollable list.

    It is recommended to leave this set to false if the amount of actions is large, as this can cause very large diffs to be sent to the client. However, if the number of actions in the palette is relatively short, this can be set to true to show the user all available actions.

    Defaults to false.

  • icon_component (:any) - The icon component is the functional component that is used to render icons in the Palette's results list. It defaults to the icon component that is generated by Phoenix's app generator, which is based on Heroicons and your tailwind.config.js embedding the Heroicons properly in CSS.

    However, it can be overridden to be any icon component that you would like to use.

    The icon component must conform to the same contract as the default icon component - it will receive a :name as a string and a :class as a string in its assigns and that's it, in order to maintain compatibility with the default component.

    Defaults to &LivePalette.Icon.icon/1.