Skip to content

Latest commit

 

History

History
181 lines (147 loc) · 7.67 KB

API-Style.md

File metadata and controls

181 lines (147 loc) · 7.67 KB
Raw

< Back to README

Style API

We support two approaches to styling.

CSS variables

You can override CSS variables that we expose, and change them to your preferred value.

This works best for making minor changes, such as changing the link and highlight color, or creating a dark mode. Copy or import the typesense-minibar.css stylesheet, then override any of the below variables from your own stylesheet.

Note: Set variables on the .tsmb-form or typesense-minibar selector only. The variables are automatically picked up by the internal more specific selectors. You don't have to write any custom CSS rules!

Text sizes:

  • --tsmb-size-base: Size of input text, group headings, and major whitespace.
  • --tsmb-size-sm: Size of search results (title and excerpt), icon text (slash), and minor whitespace.
  • --tsmb-size-input: Height of input field.

Misc sizes:

  • --tsmb-size-edge: Line thickness of edges, e.g. border-width.
  • --tsmb-size-radius: Roundness, e.g. border-radius.
  • --tsmb-size-highlight: Line thickness of cursor highlight, e.g. border-left-width.
  • --tsmb-size-listbox-width: The maximum width of the listbox. The minimum is always the width of the input field.
  • --tsmb-size-listbox-max-height: The maximum height of the listbox.
  • --tsmb-size-listbox-right: Set to 0 to create a right-aligned listbox that expands to the left.

Base layout, for idle or inactive input field:

  • --tsmb-color-base-background: Background color, e.g. white in lightmode.
  • --tsmb-color-base30: Hard constrast (for input text), e.g. dark grey in lightmode.
  • --tsmb-color-base50: Medium contrast (for input placeholder), e.g. medium grey in lightmode.
  • --tsmb-color-base90: Subtle contrast (for lines, slash icon), e.g. light pastel in lightmode.

Active layout, for active input field and result box. Defaults to the same colors as above.

  • --tsmb-color-focus-background: Background color, e.g. white in lightmode.
  • --tsmb-color-focus30: Hard contrast (focussed input text).
  • --tsmb-color-focus50: Medium contrast (for search result excerpt, focussed placeholder, footer).
  • --tsmb-color-focus90: Subtle contrast (for result borders).

Primary colors, by default only used in the active layout:

  • --tsmb-color-primary30: Hard contrast, for colorful dark background or dark text.
  • --tsmb-color-primary50: Medium contrast, for colorful links or buttons.
  • --tsmb-color-primary90: Subtle contrast, for selection background.

Example (Web Component):

/* Dark theme for inactive input field. */
typesense-minibar {
  --tsmb-color-base-background: #691c69;
  --tsmb-color-base30: #390f39;
  --tsmb-color-base50: #c090c0;
  --tsmb-color-base90: #c090c0;
}

Example (class):

/* Dark theme for inactive input field. */
.tsmb-form {
  --tsmb-color-base-background: #691c69;
  --tsmb-color-base30: #390f39;
  --tsmb-color-base50: #c090c0;
  --tsmb-color-base90: #c090c0;
}

Semantic HTML

Alternatively, you can opt-out of the accompanying stylesheet and make your own! In that case, we recommend you target the documented selectors below.

Selector Description
.tsmb-form--slash … Pressing a slash will activate this form. Use as basis for longer selectors.

This selector matches after the JavaScript code has run, unless configured with data-slash=false). This ensures you can safely use it to create a slash icon, and trust that it won't be displayed if JavaScript failed, was unsupported, or was disabled.

Example: .tsmb-form--slash:not(:focus-within)::after { content: '/'; }
.tsmb-form--open The form currently has an open result box.
.tsmb-form[data-group=true] …

typesense-minibar[data-group=true] …		 Override styled when using grouped results. Use as basis for longer selectors.
.tsmb-form input[type=search]

.tsmb-form input[type=search]::placeholder

typesense-minibar input[type=search]		 Input field.
.tsmb-form [role=listbox]

typesense-minibar [role=listbox]		 Dropdown menu, populated with either one or more search results, or .tsmb-empty. When the results are closed, this element is hidden by setting the native hidden attribute.
.tsmb-form [role=option]

.tsmb-form [role=option][aria-selected=true]

typesense-minibar [role=option]		 Search result.
.tsmb-form [role=option] a

typesense-minibar [role=option] a		 Clickable portion of result (title + content). This covers the full search result, except when results are grouped, then the first result in a group additionally contains .tsmb-suggestion_group outside the clickable portion.
.tsmb-form [role=option] mark

typesense-minibar [role=option] mark		 Matching characters or words, e.g. in the excerpt.
.tsmb-suggestion_group Group heading, may appear if the form is configured with data-group=true.
.tsmb-suggestion_title Page title and optionally heading breadcrumbs to the matching paragraph.
.tsmb-suggestion_content Page excerpt, typically a matching sentence.
.tsmb-empty                                                                                            Placeholder when there are no results.
.tsmb-icon-close SVG injected by JavaScript. Hidden by default. A click handler is bound that will close the results. It is recommended to make this visible only when results are visible.

Example:
.tsmb-form--open .tsmb-icon-close { display: block !important; }

Example DOM, stripped of internal details:

<typesense-minibar data-origin="…" data-collection="…" data-key="…">
  <form role="search">
    <input type="search">

    <div role="listbox">
      <div role="option" aria-selected="true">
        <a href="…">
          <div class="tsmb-suggestion_title">…</div>
          <div class="tsmb-suggestion_content">…</div>
        </a>
      </div>
      <div role="option">…</div>
    </div>

    <svg class="tsmb-icon-close">…</svg>
  </form>
</typesense-minibar>

Example DOM, when using the HTML class:

<form role="search" class="tsmb-form"
      data-origin="…" data-collection="…" data-key="…">
  <input type="search">

  <div role="listbox">
    <div role="option" aria-selected="true">
      <a href="…">
        <div class="tsmb-suggestion_title">…</div>
        <div class="tsmb-suggestion_content">…</div>
      </a>
    </div>
    <div role="option">…</div>
  </div>

  <svg class="tsmb-icon-close">…</svg>
</form>

Example DOM, when using data-group=true:

<typesense-minibar data-origin="…" data-collection="…" data-key="…"
                   data-group="true">
  <form role="search">
    <input type="search">

    <div role="listbox">
      <div role="option">
        <div class="tsmb-suggestion_group">My Group</div>
        <a href="…">…</a>
      </div>
      <div role="option">
        <a href="…">…</a>
      </div>
      <div role="option">
        <div class="tsmb-suggestion_group">My Second Group</div>
        <a href="…">…</a>
      </div>
    </div>

    <svg class="tsmb-icon-close">…</svg>
  </form>
</typesense-minibar>

Example DOM, when using data-foot=true:

<typesense-minibar data-origin="…" data-collection="…" data-key="…"
                   data-foot="true">
  <form role="search">
    <input type="search">

    <div role="listbox">
      <div role="option">…</div>
      <div role="option">…</div>
      <a class="tsmb-foot" href="https://typesense.org" title="Search by Typesense"></a>
    </div>

    <svg class="tsmb-icon-close">…</svg>
  </form>
</typesense-minibar>