Sefirot

Appearance

SInputImage ​

<SInputFile> is a file select input component.

@globalbrain/sefirot/lib/components/SInputImage.vue

JPG or PNG. 500KB max.

Usage ​

The only required prop is :value or v-model. The value of the input is a File object and must be image file that can be rendered on the browser. The input will not automatically validate the file type. You should use :accept prop to limit the selectable file types, or use :validation prop to validate the file type.

vue
<script setup lang="ts">
import { shallowRef } from 'vue'
import SInputImage from '@globalbrain/sefirot/lib/components/SInputImage.vue'

const input = shallowRef<File | null>(null)
</script>

<template>
  <SInputImage v-model="input" />
</template>
<script setup lang="ts">
import { shallowRef } from 'vue'
import SInputImage from '@globalbrain/sefirot/lib/components/SInputImage.vue'

const input = shallowRef<File | null>(null)
</script>

<template>
  <SInputImage v-model="input" />
</template>

Props ​

Here are the list of props you may pass to the component.

:size ​

Defines the size of the input. The default is small.

ts
interface Props {
  size?: 'mini' | 'small' | 'medium'
}
interface Props {
  size?: 'mini' | 'small' | 'medium'
}
template
<SInputImage size="small" v-model="..." />
<SInputImage size="small" v-model="..." />

:label ​

Defines the label text of the input.

ts
interface Props {
  label?: string
}
interface Props {
  label?: string
}
template
<SInputImage label="Upload image" v-model="..." />
<SInputImage label="Upload image" v-model="..." />

:info ​

Shows help icon after the label and shows info in a tooltip when the user hovers the label.

ts
interface Props {
  info?: string
}
interface Props {
  info?: string
}
template
<SInputImage
  label="Upload image"
  info="This will be used as your avatar."
  v-model="..."
/>
<SInputImage
  label="Upload image"
  info="This will be used as your avatar."
  v-model="..."
/>

:note ​

Adds small help text after the label. Best used along with label prop.

ts
interface Props {
  note?: string
}
interface Props {
  note?: string
}
template
<SInputImage
  label="Upload file"
  note="Optional"
  v-model="..."
/>
<SInputImage
  label="Upload file"
  note="Optional"
  v-model="..."
/>

:help ​

Adds small help text to the bottom of the input.

ts
interface Props {
  help?: string
}
interface Props {
  help?: string
}
template
<SInputImage
  label="Upload file"
  help="JPG or PNG. 500KB max."
  v-model="..."
/>
<SInputImage
  label="Upload file"
  help="JPG or PNG. 500KB max."
  v-model="..."
/>

:check-icon ​

Icon to display at corner right of label. Useful to show the status of a particular input.

ts
import { IconifyIcon } from '@iconify/vue/dist/offline'

interface Props {
  checkIcon?: IconifyIcon
}
import { IconifyIcon } from '@iconify/vue/dist/offline'

interface Props {
  checkIcon?: IconifyIcon
}
template
<SInputImage :check-icon="IconCheckCircle" v-model="..." />
<SInputImage :check-icon="IconCheckCircle" v-model="..." />

:check-text ​

Text to display alongside check-icon.

ts
interface Props {
  checkText?: string
}
interface Props {
  checkText?: string
}
template
<SInputImage :check-text="Saved" v-model="..." />
<SInputImage :check-text="Saved" v-model="..." />

:check-color ​

Defines the color of check-icon and check-text. The default is neutral.

ts
interface Props {
  checkColor?: Color
}

type Color =
  | 'neutral' 
  | 'mute' 
  | 'info' 
  | 'success' 
  | 'warning' 
  | 'danger'
interface Props {
  checkColor?: Color
}

type Color =
  | 'neutral' 
  | 'mute' 
  | 'info' 
  | 'success' 
  | 'warning' 
  | 'danger'
template
<SInputImage
  :check-icon="IconCheckCircle"
  check-text="Saved"
  check-color="success"
  v-model="..." />
/>
<SInputImage
  :check-icon="IconCheckCircle"
  check-text="Saved"
  check-color="success"
  v-model="..." />
/>

:image-type ​

The type of image to display. The type can be eitehr rectangle or circle. The default is rectangle.

ts
interface Props {
  imageType?: ImageType
}

type ImageType = 'rectangle' | 'circle'
interface Props {
  imageType?: ImageType
}

type ImageType = 'rectangle' | 'circle'
template
<SInputImage image-type="circle" v-model="..." />
<SInputImage image-type="circle" v-model="..." />

:image-width ​

The width of the image placeholder. The default is 96px. You may also control the width by --input-image-width CSS variable. Using CSS variable is recommended when you need responsive design.

ts
interface Props {
  imageWidth?: string
}
interface Props {
  imageWidth?: string
}
template
<SInputImage image-with="128px" v-model="..." />
<SInputImage image-with="128px" v-model="..." />

:image-aspect-ratio ​

Set the aspect ratio of the image placeholder. The default is 1 / 1. The value is directly passed to CSS property aspect-ratio.

ts
interface Props {
  imageAspectRatio?: string
}
interface Props {
  imageAspectRatio?: string
}
template
<SInputImage image-aspect-ratio="16 / 9" v-model="..." />
<SInputImage image-aspect-ratio="16 / 9" v-model="..." />

:select-text ​

The text for the "select image" button. The default is Select image.

ts
interface Props {
  selectText?: string
}
interface Props {
  selectText?: string
}
template
<SInputImage select-text="Upload" v-model="..." />
<SInputImage select-text="Upload" v-model="..." />

:remove-text ​

The text for the "remove image" button. The default is Remove image.

ts
interface Props {
  removeText?: string
}
interface Props {
  removeText?: string
}
template
<SInputImage remove-text="Delete" v-model="..." />
<SInputImage remove-text="Delete" v-model="..." />

:accept ​

Defines the file types to accept.

ts
interface Props {
  accept?: string
}
interface Props {
  accept?: string
}
template
<SInputImage accept="image/*" v-model="..." />
<SInputImage accept="image/*" v-model="..." />

:nullable ​

Whether a user can remove the selected image. The default is true.

ts
interface Props {
  nullable?: boolean
}
interface Props {
  nullable?: boolean
}
template
<SInputImage :nullable="false" v-model="..." />
<SInputImage :nullable="false" v-model="..." />

:disabled ​

Disbale the input. When disabled, the user cannot select nor remove file. The default is false.

ts
interface Props {
  disabled?: boolean
}
interface Props {
  disabled?: boolean
}
template
<SInputImage disabled v-model="..." />
<SInputImage disabled v-model="..." />

:value ​

Sets the input value. When model-value prop is set (e.g. via v-model directive), this prop gets ignored.

ts
interface Props {
  value?: File |  null
}
interface Props {
  value?: File |  null
}
template
<SInputImage :value="file" />
<SInputImage :value="file" />

:model-value ​

The v-model binding for the input.

ts
interface Props {
  modelValue?: File | null
}
interface Props {
  modelValue?: File | null
}
template
<SInputImage v-model="file" />
<SInputImage v-model="file" />

:validation ​

The validation object for the input. It accepts Vuelidate like validation object and displays error if there're any.

ts
import { Ref } from 'vue'

interface Props {
  validation?: Validatable
}

export interface Validatable {
  readonly $dirty: boolean
  readonly $invalid: boolean
  readonly $errors: ValidatableError[]
  readonly $touch: () => void
}

export interface ValidatableError {
  readonly $message: string | Ref<string>
}
import { Ref } from 'vue'

interface Props {
  validation?: Validatable
}

export interface Validatable {
  readonly $dirty: boolean
  readonly $invalid: boolean
  readonly $errors: ValidatableError[]
  readonly $touch: () => void
}

export interface ValidatableError {
  readonly $message: string | Ref<string>
}
template
<SInputImage
  v-model="file"
  :validation="validation"
/>
<SInputImage
  v-model="file"
  :validation="validation"
/>

:hide-error ​

Stop showing validation error message even when there are errors. This prop will not prevent the error color from appearing.

ts
interface Props {
  hideError?: boolean
}
interface Props {
  hideError?: boolean
}
template
<SInputImage
  v-model="file"
  :validation="validation"
  hide-error
/>
<SInputImage
  v-model="file"
  :validation="validation"
  hide-error
/>

Slots ​

Here are the list of slots you may define within the component.

#info ​

Same as info prop. When info prop and this slot are defined at the same time, this slot will take precedence.

template
<SInputImage label="Upload image" v-model="...">
  <template #info>
    Learn more about this field <SLink href="...">here</SLink>.
  </template>
</SInputImage>
<SInputImage label="Upload image" v-model="...">
  <template #info>
    Learn more about this field <SLink href="...">here</SLink>.
  </template>
</SInputImage>

Events ​

Here are the list of events the component may emit.

@update:model-value ​

Emits when the user selects the item. This event is always emitted together with change event.

ts
interface Emits {
  (e: 'update:model-value', value: File | null): void
}
interface Emits {
  (e: 'update:model-value', value: File | null): void
}

@change ​

Emits when the user selects the item. This event is always emitted together with update:model-value event.

ts
interface Emits {
  (e: 'change', value: File | null): void
}
interface Emits {
  (e: 'change', value: File | null): void
}

Styles ​

You may customize the styles by overriding --input prefixed CSS variables.

Global input styles ​

You may customize the various styles of the component via global input related CSS variables. Please refer to Styles: Input Styles page.

Image placeholder width ​

Use --input-image-width to set the width of the image placeholder. When set, this variable will override :image-width.

css
:root {
  --input-image-width: undefined;
}
:root {
  --input-image-width: undefined;
}