Hints

Source@dopt/vue

Overview

The hints component is powered by a hints block and is great way to call attetnion to UI elements to help users discover new features, provide contextual help, or nudge them towards a good next step.

A hints block is comprised of items, which are the unordered set of hints.

The hints component exposes two composables to easily build product hints.

Composables

With our Vue SDK, you can use hints and hints items headlessly by importing the useHints or useHintsItem composable from @dopt/vue.

useHints

• useHints(id: string): Hints

A Vue composable for accessing and updating a hints' state.

<script>
  import { useHints } from '@dopt/vue';
  const {
    id,
    items,
    active,
    completed,
    dismissed,
    complete,
    dismiss,
    filter,
    count,
    size,
  } = useHints('onboarding-hints.hints-component');
</script>

<template>
  <div>
    <div id="states">
      <div>hints.active: {{ active }}</div>
      <div>hints.completed: {{ completed }}</div>
      <div>hints.dismissed: {{ dismissed }}</div>
    </div>
    <div id="actions">
      <button v-on:click="() => complete()">Complete</button>
      <button v-on:click="() => dismiss()">Dismiss</button>
    </div>
    <div id="children">
      hints.items: {{ items.map(item => item.id).join(' ') }}
    </div>
    <div id="filtering">
      <div id="active-items">
        {{ filter('active').map(item => item.id).join(' ') }}
      </div>
      <div id="not-active-items">
        {{ filter('not-active').map(item => item.id).join(' ') }}
      </div>
      <div id="completed-items">
        {{ filter('completed').map(item => item.id).join(' ') }}
      </div>
      <div id="not-completed-items">
        {{ filter('not-completed').map(item => item.id).join(' ') }}
      </div>
      <div id="dismissed-items">
        {{ filter('dismissed').map(item => item.id).join(' ') }}
      </div>
      <div id="not-dismissed-items">
        {{ filter('not-dismissed').map(item => item.id).join(' ') }}
      </div>
    </div>
    <div id="metadata">
      <div>hints.size: {{ size }}</div>
    </div>
  </div>
</template>

useHintsItem

• useHintsItem(id): HintsItem

A Vue composable for accessing and updating a hints item's state and content.

<script>
  import { useHintsItem } from '@dopt/vue';
  import RichText from '@dopt/html-rich-text';
  const {
    id,
    hints,
    title,
    body,
    completeLabel,
    dismissAllLabel,
    active,
    completed,
    next,
    back,
  } = useHintsItem('onboarding-hints.step-1');
</script>

<template>
  <div>
    <div id="states">
      <div>hintsItem.active: {{ active }}</div>
      <div>hintsItem.completed: {{ completed }}</div>
    </div>
    <div id="actions">
      <button v-on:click="() => next()">{{ completeLabel }}</button>
      <button v-on:click="() => back()">{{ dismissAllLabel }}</button>
    </div>
    <div id="content">
      <div>hintsItem.title: {{ title }}</div>
      <div>
        hintsItem.body: <div v-html="RichText({ content: body })"></div>
      </div>
      <div>hintsItem.completeLabel: {{ completeLabel }}</div>
      <div>hintsItem.dismissAllLabel: {{ dismissAllLabel }}</div>
    </div>
    <div id="parent">
      <div>hintsItem.hints: {{ hints()?.id?.value }}</div>
    </div>
    <div id="metadata">
      <div>hintsItem.index: {{ hintsItem.index }}</div>
    </div>
  </div>
</template>

Types

Hints

A stateful container for hints items.

interface Hints {
  id: Ref<string>;

  items: () => HintsItem[];

  active: Ref<boolean>;

  completed: Ref<boolean>;
  dismissed: Ref<boolean>;

  field: <V>(name: string) => undefined | null | V; 

  complete: () => void;
  dismiss: () => void;

  size: Ref<number>;

  filter(on: FilterableField): HintsItem[];
  count(where: CountableField): number;
}

HintsItem

A child of the hints. Includes state accessors and methods for updating state along with content configured in Dopt.

interface HintsItem {
  id: Ref<string>;

  hints: () => Hints | undefined;

  index: Ref<number | null | undefined>;

  title: Ref<string | null | undefined>;
  body: Ref<Children | null | undefined>;

  completeLabel: Ref<string | null | undefined>;
  dismissAllLabel: Ref<string | null | undefined>;

  active: Ref<boolean>;

  completed: Ref<boolean>;
  dismissed: Ref<boolean>;

  field: <V>(name: string) => undefined | null | V; 

  next: () => void;
  back: () => void;
}

FilterableField

type FilterableField = 'completed' | 'not-completed' | 'dismissed' | 'not-dismissed' | 'active' | 'not-active' | 'done' | 'not-done';

CountableField

type CountableField = FilterableField;