Class: Primer::Beta::AutoComplete

Inherits:
Component
  • Object
show all
Defined in:
app/components/primer/beta/auto_complete.rb,
app/components/primer/beta/auto_complete/item.rb

Overview

Use AutoComplete to provide a user with a list of selectable suggestions that appear when they type into the input field. This list is populated by server search results.

Defined Under Namespace

Classes: Item

Constant Summary collapse

DEFAULT_SIZE = 
:medium
SIZE_MAPPINGS = 
{
  :small => "FormControl-small",
  DEFAULT_SIZE => "FormControl-medium",
  :large => "FormControl-large"
}.freeze
SIZE_OPTIONS = 
SIZE_MAPPINGS.keys

Constants inherited from Component

Component::INVALID_ARIA_LABEL_TAGS

Constants included from Status::Dsl

Status::Dsl::STATUSES

Constants included from ViewHelper

ViewHelper::HELPERS

Constants included from TestSelectorHelper

TestSelectorHelper::TEST_SELECTOR_TAG

Constants included from FetchOrFallbackHelper

FetchOrFallbackHelper::InvalidValueError

Instance Method Summary collapse

Methods included from JoinStyleArgumentsHelper

#join_style_arguments

Methods included from TestSelectorHelper

#add_test_selector

Methods included from FetchOrFallbackHelper

#fetch_or_fallback, #fetch_or_fallback_boolean, #silence_deprecations?

Methods included from ClassNameHelper

#class_names

Constructor Details

#initialize(label_text:, src:, list_id:, input_id:, input_name: nil, placeholder: nil, show_clear_button: false, visually_hide_label: false, size: DEFAULT_SIZE, full_width: false, disabled: false, invalid: false, inset: false, monospace: false, **system_arguments) ⇒ AutoComplete

Returns a new instance of AutoComplete.

Examples:

Leading visual

@description
  Display any Octicon as a leading visual within the field
@code
  <%= render(Primer::Beta::AutoComplete.new(label_text: "Select a fruit", src: "/auto_complete", input_id:"input-id-1", list_id: "list-id-1")) do |c| %>
    <% c.leading_visual_icon(icon: :search) %>
  <% end %>

Trailing action

@description
  Show a clear button
@code
  <%= render(Primer::Beta::AutoComplete.new(label_text: "Select a fruit", input_id: "input-id-2", list_id: "list-id-2", src: "/auto_complete", show_clear_button: true )) %>

Visually hidden label

@description
  A non-visible label may be rendered with `visually_hide_label: true`, but it is highly discouraged. See <%= link_to_accessibility %>.
@code
  <%= render(Primer::Beta::AutoComplete.new(label_text: "Select a fruit", input_id: "fruits-input--custom-results-1", list_id: "fruits-popup--custom-result-1", src: "/auto_complete", visually_hide_label: true)) do |c| %>
    <% c.leading_visual_icon(icon: :search) %>
  <% end %>

Full width field

@description
  To allow field to span width of its container, set `full_width` to `true`.
@code
  <%= render(Primer::Beta::AutoComplete.new(label_text: "Select a fruit", input_id: "fruits-input--custom-results-2", list_id: "fruits-popup--custom-results-2", src: "/auto_complete", full_width: true)) do |c| %>
    <% c.leading_visual_icon(icon: :search) %>
  <% end %>

Inset variant

@description
  Use the `inset` variant to change the input background color to be subtle.
@code
  <%= render(Primer::Beta::AutoComplete.new(label_text: "Select a fruit", input_id: "fruits-input--custom-results-2", list_id: "fruits-popup--custom-results-2", src: "/auto_complete", inset: true)) do |c| %>
    <% c.leading_visual_icon(icon: :search) %>
  <% end %>

Monospace variant

@description
  Use the `monospace` variant to change the input font family.
@code
  <%= render(Primer::Beta::AutoComplete.new(label_text: "Select a fruit", input_id: "fruits-input--custom-results-2", list_id: "fruits-popup--custom-results-2", src: "/auto_complete", monospace: true)) do |c| %>
    <% c.leading_visual_icon(icon: :search) %>
  <% end %>

With custom classes for the input

<%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", input_id: "fruits-input--custom-input", list_id: "fruits-popup--custom-input")) do |c| %>
  <% c.input(classes: "custom-class") %>
<% end %>

With custom classes for the results

<%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", input_id: "fruits-input--custom-results", list_id: "fruits-popup--custom-results")) do |c| %>
  <% c.results(classes: "custom-class") %>
<% end %>

Parameters:

  • label_text (String) —

    The label of the input.

  • src (String) —

    The route to query.

  • input_id (String) —

    Id of the input element.

  • input_name (String) (defaults to: nil) —

    Optional name of the input element, defaults to input_id when not set.

  • list_id (String) —

    Id of the list element.

  • visually_hide_label (Boolean) (defaults to: false) —

    Controls if the label is visible. If true, screen reader only text will be added.

  • show_clear_button (Boolean) (defaults to: false) —

    Adds optional clear button.

  • system_arguments (Hash) —

    <%= link_to_system_arguments_docs %>

  • size (Hash) (defaults to: DEFAULT_SIZE) —

    Input size can be small, medium (default), or large

  • full_width (Boolean) (defaults to: false) —

    Input can be full-width or fit to content

  • disabled (Boolean) (defaults to: false) —

    Disabled input

  • invalid (Boolean) (defaults to: false) —

    Invalid input

  • placeholder (String) (defaults to: nil) —

    The placeholder text displayed within the input

  • inset (Boolean) (defaults to: false) —

    subtle input background color

  • monospace (Boolean) (defaults to: false) —

    monospace input font family



164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'app/components/primer/beta/auto_complete.rb', line 164

def initialize(label_text:, src:, list_id:, input_id:, input_name: nil, placeholder: nil, show_clear_button: false, visually_hide_label: false, size: DEFAULT_SIZE, full_width: false, disabled: false, invalid: false, inset: false, monospace: false, **system_arguments)
  @label_text = label_text
  @list_id = list_id
  @input_id = input_id
  @input_name = input_name || input_id
  @placeholder = placeholder
  @visually_hide_label = visually_hide_label
  @show_clear_button = show_clear_button
  @system_arguments = deny_tag_argument(**system_arguments)
  @system_arguments[:tag] = "auto-complete"
  @system_arguments[:src] = src
  @system_arguments[:for] = list_id
  @disabled = disabled
  @invalid = invalid
  @size = size
  @inset = inset
  @monospace = monospace
  @full_width = full_width
  @field_wrap_classes = class_names(
    "FormControl-input-wrap",
    SIZE_MAPPINGS[fetch_or_fallback(SIZE_OPTIONS, @size, DEFAULT_SIZE)],
    "FormControl-input-wrap--trailingAction": show_clear_button
  )
  @form_group_classes = class_names(
    "FormControl",
    "FormControl--fullWidth": full_width
  )
end

Instance Method Details

#before_render ⇒ Object

add input and results without needing to explicitly call them in the view



194
195
196
197
 
# File 'app/components/primer/beta/auto_complete.rb', line 194

def before_render
  results(classes: "") unless results
  input(classes: "") unless input
end